Merge branch 'fix.renderer-interfaces'

5 files changed, 47 insertions, 28 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 15b1b910e..203db1a44 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -65,6 +65,9 @@ Documentation
 - Removed mention of ``pyramid_beaker`` from docs.  Beaker is no longer 
   maintained.  Point people at ``pyramid_redis_sessions`` instead.
 
+- Add documentation for ``pyramid.interfaces.IRendererFactory`` and
+  ``pyramid.interfaces.IRenderer``.
+
 Backwards Incompatibilities
 ---------------------------
 
@@ -78,6 +81,10 @@ Backwards Incompatibilities
 Deprecations
 ------------
 
+- Deprecate the ``pyramid.interfaces.ITemplateRenderer`` interface. It was
+  ill-defined and became unused when Mako and Chameleon template bindings were
+  split into their own packages.
+
 - The ``pyramid.session.UnencryptedCookieSessionFactoryConfig`` API has been 
   deprecated and is superseded by the 
   ``pyramid.session.SignedCookieSessionFactory``.  Note that while the cookies
diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index 1dea5fab0..d8d935afd 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -50,7 +50,10 @@ Other Interfaces
   .. autointerface:: IRendererInfo
      :members:
 
-  .. autointerface:: ITemplateRenderer
+  .. autointerface:: IRendererFactory
+     :members:
+
+  .. autointerface:: IRenderer
      :members:
 
   .. autointerface:: IViewMapperFactory
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 740c81555..4f8c4bf77 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -480,8 +480,11 @@ Adding a New Renderer
 You may add a new renderer by creating and registering a :term:`renderer
 factory`.
 
-A renderer factory implementation is typically a class with the
-following interface:
+A renderer factory implementation should conform to the
+:class:`pyramid.interfaces.IRendererFactory` interface. It should be capable
+of creating an object that conforms to the
+:class:`pyramid.interfaces.IRenderer` interface. A typical class that follows
+this setup is as follows:
 
 .. code-block:: python
    :linenos:
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 85b2227b4..cf651cf1e 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -367,9 +367,29 @@ class IBeforeRender(IDict):
                               '``render`` method for this rendering. '
                               'This feature is new in Pyramid 1.2.')
 
+class IRendererInfo(Interface):
+    """ An object implementing this interface is passed to every
+    :term:`renderer factory` constructor as its only argument (conventionally
+    named ``info``)"""
+    name = Attribute('The value passed by the user as the renderer name')
+    package = Attribute('The "current package" when the renderer '
+                        'configuration statement was found')
+    type = Attribute('The renderer type name')
+    registry = Attribute('The "current" application registry when the '
+                         'renderer was created')
+    settings = Attribute('The deployment settings dictionary related '
+                         'to the current application')
+
+class IRendererFactory(Interface):
+    def __call__(info):
+        """ Return an object that implements
+        :class:`pyramid.interfaces.IRenderer`. ``info`` is an
+        object that implements :class:`pyramid.interfaces.IRendererInfo`.
+        """
+
 class IRenderer(Interface):
     def __call__(value, system):
-        """ Call a the renderer implementation with the result of the
+        """ Call the renderer with the result of the
         view (``value``) passed in and return a result (a string or
         unicode object useful as a response body).  Values computed by
         the system are passed by the system in the ``system``
@@ -387,6 +407,13 @@ class ITemplateRenderer(IRenderer):
         accepts arbitrary keyword arguments and returns a string or
         unicode object """
 
+deprecated(
+    'ITemplateRenderer',
+    'As of Pyramid 1.5 the, "pyramid.interfaces.ITemplateRenderer" interface '
+    'is scheduled to be removed. It was used by the Mako and Chameleon '
+    'renderers which have been split into their own packages.'
+    )
+
 class IViewMapper(Interface):
     def __call__(self, object):
         """ Provided with an arbitrary object (a function, class, or
@@ -611,17 +638,13 @@ class ITraverser(Interface):
 
 ITraverserFactory = ITraverser # b / c for 1.0 code
 
-class IRendererFactory(Interface):
-    def __call__(info):
-        """ Return an object that implements ``IRenderer``.  ``info`` is an
-        object that implement ``IRendererInfo``.  """
-
 class IViewPermission(Interface):
     def __call__(context, request):
-        """ Return True if the permission allows, return False if it denies. """
+        """ Return True if the permission allows, return False if it denies.
+        """
 
 class IRouter(Interface):
-    """WSGI application which routes requests to 'view' code based on
+    """ WSGI application which routes requests to 'view' code based on
     a view registry."""
     registry = Attribute(
         """Component architecture registry local to this application.""")
@@ -932,20 +955,6 @@ class ISession(IDict):
         returned.
         """
 
-class IRendererInfo(Interface):
-    """ An object implementing this interface is passed to every
-    :term:`renderer factory` constructor as its only argument (conventionally
-    named ``info``)"""
-    name = Attribute('The value passed by the user as the renderer name')
-    package = Attribute('The "current package" when the renderer '
-                        'configuration statement was found')
-    type = Attribute('The renderer type name')
-    registry = Attribute('The "current" application registry when the '
-                         'renderer was created')
-    settings = Attribute('The deployment settings dictionary related '
-                         'to the current application')
-
-
 class IIntrospector(Interface):
     def get(category_name, discriminator, default=None):
         """ Get the IIntrospectable related to the category_name and the
diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py
index be2865d30..4924fff57 100644
--- a/pyramid/tests/test_config/test_views.py
+++ b/pyramid/tests/test_config/test_views.py
@@ -40,9 +40,6 @@ class TestViewsConfigurationMixin(unittest.TestCase):
 
     def _registerRenderer(self, config, name='.txt'):
         from pyramid.interfaces import IRendererFactory
-        from pyramid.interfaces import ITemplateRenderer
-        from zope.interface import implementer
-        @implementer(ITemplateRenderer)
         class Renderer:
             def __init__(self, info):
                 self.__class__.info = info