- Deprecated the ``set_renderer_globals_factory`` method of the Configurator

  and the ``renderer_globals`` Configurator constructor parameter.

6 files changed, 93 insertions, 34 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 9bf8197ab..d2b97ece6 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -16,6 +16,12 @@ Features
 - Add JSONP renderer (see "JSONP renderer" in the Renderers chapter of the
   documentation).
 
+Deprecations
+------------
+
+- Deprecated the ``set_renderer_globals_factory`` method of the Configurator
+  and the ``renderer_globals`` Configurator constructor parameter.
+
 1.1a3 (2011-06-26)
 ==================
 
diff --git a/docs/api/config.rst b/docs/api/config.rst
index 274ee0292..71ef4a746 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -74,7 +74,7 @@
 
      .. automethod:: set_request_factory
 
-     .. automethod:: set_renderer_globals_factory
+     .. automethod:: set_renderer_globals_factory(factory)
 
      .. automethod:: set_view_mapper
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 1c8a64fd7..56c566a4c 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -183,6 +183,10 @@ already constructed a :term:`configurator` it can also be registered via the
 Adding Renderer Globals
 -----------------------
 
+.. warning:: this feature is deprecated as of Pyramid 1.1.  A non-deprecated
+   mechanism which allows event subscribers to add renderer global values
+   is documented in :ref:`beforerender_event`.
+
 Whenever :app:`Pyramid` handles a request to perform a rendering (after a
 view with a ``renderer=`` configuration attribute is invoked, or when any
 of the methods beginning with ``render`` within the :mod:`pyramid.renderers`
@@ -227,9 +231,6 @@ already constructed a :term:`configurator` it can also be registered via the
    config = Configurator()
    config.set_renderer_globals_factory(renderer_globals_factory)
 
-Another mechanism which allows event subscribers to add renderer global values
-exists in :ref:`beforerender_event`.
-
 .. index::
    single: before render event
 
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index 7d0f666d3..3252cba22 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -364,6 +364,12 @@ Deprecations and Behavior Differences
   within a static view returns the index.html properly.  See also
   https://github.com/Pylons/pyramid/issues/67.
 
+- Deprecated the
+  :meth:`pyramid.config.Configurator.set_renderer_globals_factory` method and
+  the ``renderer_globals`` Configurator constructor parameter.  Users should
+  use convert code using this feature to use a BeforeRender event als
+  :ref:`beforerender_event`.
+
 Dependency Changes
 ------------------
 
diff --git a/pyramid/config.py b/pyramid/config.py
index d27d35464..bf3793c26 100644
--- a/pyramid/config.py
+++ b/pyramid/config.py
@@ -215,6 +215,10 @@ class Configurator(object):
     See :ref:`adding_renderer_globals`.  By default, it is ``None``, which
     means use no renderer globals factory.
 
+    .. warning:: as of Pyramid 1.1, ``renderer_globals_factory`` is
+       deprecated.  Instead, use a BeforeRender event subscriber as per
+       :ref:`beforerender_event`.
+
     If ``default_permission`` is passed, it should be a
     :term:`permission` string to be used as the default permission for
     all view configuration registrations performed against this
@@ -736,9 +740,18 @@ class Configurator(object):
             request_factory = self.maybe_dotted(request_factory)
             self.set_request_factory(request_factory)
         if renderer_globals_factory:
+            warnings.warn(
+                'Passing ``renderer_globals_factory`` as a Configurator '
+                'constructor parameter is deprecated as of Pyramid 1.1. '
+                'Use a BeforeRender event subscriber as documented in the '
+                '"Hooks" chapter of the Pyramid narrative documentation '
+                'instead',
+                DeprecationWarning,
+                2)
             renderer_globals_factory = self.maybe_dotted(
                 renderer_globals_factory)
-            self.set_renderer_globals_factory(renderer_globals_factory)
+            self.set_renderer_globals_factory(renderer_globals_factory,
+                                              warn=False)
         if default_permission:
             self.set_default_permission(default_permission)
         if session_factory is not None:
@@ -2105,7 +2118,7 @@ class Configurator(object):
         self.action(IRequestFactory, register)
 
     @action_method
-    def set_renderer_globals_factory(self, factory):
+    def set_renderer_globals_factory(self, factory, warn=True):
         """ The object passed as ``factory`` should be an callable (or
         a :term:`dotted Python name` which refers to an callable) that
         will be used by the :app:`Pyramid` rendering machinery as a
@@ -2118,10 +2131,21 @@ class Configurator(object):
         dictionary, and therefore will be made available to the code
         which uses the renderer.
 
+        .. warning:: This method is deprecated as of Pyramid 1.1.
+
         .. note:: Using the ``renderer_globals_factory`` argument
            to the :class:`pyramid.config.Configurator` constructor
            can be used to achieve the same purpose.
         """
+        if warn:
+            warnings.warn(
+                'Calling the ``set_renderer_globals`` method of a Configurator '
+                'is deprecated as of Pyramid 1.1. Use a BeforeRender event '
+                'subscriber as documented in the "Hooks" chapter of the '
+                'Pyramid narrative documentation instead',
+                DeprecationWarning,
+                3)
+
         factory = self.maybe_dotted(factory)
         def register():
             self.registry.registerUtility(factory, IRendererGlobalsFactory)
diff --git a/pyramid/tests/test_config.py b/pyramid/tests/test_config.py
index 41811782a..20fdd93e8 100644
--- a/pyramid/tests/test_config.py
+++ b/pyramid/tests/test_config.py
@@ -521,24 +521,34 @@ class ConfiguratorTests(unittest.TestCase):
         self.assertEqual(utility, pyramid.tests)
 
     def test_setup_registry_renderer_globals_factory(self):
-        from pyramid.registry import Registry
-        from pyramid.interfaces import IRendererGlobalsFactory
-        reg = Registry()
-        config = self._makeOne(reg)
-        factory = object()
-        config.setup_registry(renderer_globals_factory=factory)
-        utility = reg.getUtility(IRendererGlobalsFactory)
-        self.assertEqual(utility, factory)
+        import warnings
+        warnings.filterwarnings('ignore')
+        try:
+            from pyramid.registry import Registry
+            from pyramid.interfaces import IRendererGlobalsFactory
+            reg = Registry()
+            config = self._makeOne(reg)
+            factory = object()
+            config.setup_registry(renderer_globals_factory=factory)
+            utility = reg.getUtility(IRendererGlobalsFactory)
+            self.assertEqual(utility, factory)
+        finally:
+            warnings.resetwarnings()
 
     def test_setup_registry_renderer_globals_factory_dottedname(self):
-        from pyramid.registry import Registry
-        from pyramid.interfaces import IRendererGlobalsFactory
-        reg = Registry()
-        config = self._makeOne(reg)
-        import pyramid.tests
-        config.setup_registry(renderer_globals_factory='pyramid.tests')
-        utility = reg.getUtility(IRendererGlobalsFactory)
-        self.assertEqual(utility, pyramid.tests)
+        import warnings
+        warnings.filterwarnings('ignore')
+        try:
+            from pyramid.registry import Registry
+            from pyramid.interfaces import IRendererGlobalsFactory
+            reg = Registry()
+            config = self._makeOne(reg)
+            import pyramid.tests
+            config.setup_registry(renderer_globals_factory='pyramid.tests')
+            utility = reg.getUtility(IRendererGlobalsFactory)
+            self.assertEqual(utility, pyramid.tests)
+        finally:
+            warnings.resetwarnings()
 
     def test_setup_registry_alternate_renderers(self):
         from pyramid.registry import Registry
@@ -2415,20 +2425,32 @@ class ConfiguratorTests(unittest.TestCase):
                          dummyfactory)
 
     def test_set_renderer_globals_factory(self):
-        from pyramid.interfaces import IRendererGlobalsFactory
-        config = self._makeOne(autocommit=True)
-        factory = object()
-        config.set_renderer_globals_factory(factory)
-        self.assertEqual(config.registry.getUtility(IRendererGlobalsFactory),
-                         factory)
+        import warnings
+        warnings.filterwarnings('ignore')
+        try:
+            from pyramid.interfaces import IRendererGlobalsFactory
+            config = self._makeOne(autocommit=True)
+            factory = object()
+            config.set_renderer_globals_factory(factory)
+            self.assertEqual(
+                config.registry.getUtility(IRendererGlobalsFactory),
+                factory)
+        finally:
+            warnings.resetwarnings()
 
     def test_set_renderer_globals_factory_dottedname(self):
-        from pyramid.interfaces import IRendererGlobalsFactory
-        config = self._makeOne(autocommit=True)
-        config.set_renderer_globals_factory(
-            'pyramid.tests.test_config.dummyfactory')
-        self.assertEqual(config.registry.getUtility(IRendererGlobalsFactory),
-                         dummyfactory)
+        import warnings
+        warnings.filterwarnings('ignore')
+        try:
+            from pyramid.interfaces import IRendererGlobalsFactory
+            config = self._makeOne(autocommit=True)
+            config.set_renderer_globals_factory(
+                'pyramid.tests.test_config.dummyfactory')
+            self.assertEqual(
+                config.registry.getUtility(IRendererGlobalsFactory),
+                dummyfactory)
+        finally:
+            warnings.resetwarnings()
 
     def test_set_default_permission(self):
         from pyramid.interfaces import IDefaultPermission