Features

--------

- Add ``pyramid.config.Configurator.add_resource_url_adapter`` API method.
  See the Hooks narrative documentation section entitled "Changing How
  pyramid.request.Request.resource_url Generates a URL" for more information.
  This is not a new feature, it just provides an API for adding a resource
  url adapter without needing to use the ZCA API.

- A new interface was added: ``pyramid.interfaces.IResourceURL``.  An adapter
  implementing its interface can be used to override resource URL generation
  when ``request.resource_url`` is called.  This interface replaces the
  now-deprecated ``pyramid.interfaces.IContextURL`` interface.

- The dictionary passed to a resource's ``__resource_url__`` method (see
  "Overriding Resource URL Generation" in the "Resources" chapter) now
  contains an ``app_url`` key, representing the application URL generated
  during ``request.resource_url``.  It represents a potentially customized
  URL prefix, containing potentially custom scheme, host and port information
  passed by the user to ``request.resource_url``.  It should be used instead
  of ``request.application_url`` where necessary.

- The ``request.resource_url`` API now accepts these arguments: ``app_url``,
  ``scheme``, ``host``, and ``port``.  The app_url argument can be used to
  replace the URL prefix wholesale during url generation.  The ``scheme``,
  ``host``, and ``port`` arguments can be used to replace the respective
  default values of ``request.application_url`` partially.

- A new API named ``request.resource_path`` now exists.  It works like
  ``request.resource_url`` but produces a relative URL rather than an
  absolute one.

- The ``request.route_url`` API now accepts these arguments: ``_app_url``,
  ``_scheme``, ``_host``, and ``_port``.  The ``_app_url`` argument can be
  used to replace the URL prefix wholesale during url generation.  The
  ``_scheme``, ``_host``, and ``_port`` arguments can be used to replace the
  respective default values of ``request.application_url`` partially.

Backwards Incompatibilities
---------------------------

- The ``pyramid.interfaces.IContextURL`` interface has been deprecated.
  People have been instructed to use this to register a resource url adapter
  in the "Hooks" chapter to use to influence ``request.resource_url`` URL
  generation for resources found via custom traversers since Pyramid 1.0.

  The interface still exists and registering such an adapter still works, but
  this interface will be removed from the software after a few major Pyramid
  releases.  You should replace it with an equivalent
  ``pyramid.interfaces.IResourceURL`` adapter, registered using the new
  ``pyramid.config.Configurator.add_resource_url_adapter`` API.  A
  deprecation warning is now emitted when a
  ``pyramid.interfaces.IContextURL`` adapter is found when
  ``request.resource_url`` is called.

Misc
----

- Change ``set_traverser`` API name to ``add_traverser``.

Ref #438.

5 files changed, 89 insertions, 34 deletions

diff --git a/docs/api/config.rst b/docs/api/config.rst
index 3c5ee563a..3fc2cfc44 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -94,7 +94,7 @@
 
      .. automethod:: set_notfound_view
 
-     .. automethod:: set_traverser
+     .. automethod:: add_traverser
 
      .. automethod:: set_renderer_globals_factory(factory)
 
diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index 11cd8cf7e..1dea5fab0 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -79,3 +79,7 @@ Other Interfaces
 
   .. autointerface:: IAssetDescriptor
      :members:
+
+  .. autointerface:: IResourceURL
+     :members:
+
diff --git a/docs/api/request.rst b/docs/api/request.rst
index 1ab84e230..e1b233fbc 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -183,6 +183,8 @@
 
    .. automethod:: resource_url
 
+   .. automethod:: resource_path
+
    .. attribute::  response_*
 
       In Pyramid 1.0, you could set attributes on a
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 076f9fa5c..2c4310080 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -479,58 +479,55 @@ When you add a traverser as described in :ref:`changing_the_traverser`, it's
 often convenient to continue to use the
 :meth:`pyramid.request.Request.resource_url` API.  However, since the way
 traversal is done will have been modified, the URLs it generates by default
-may be incorrect.
+may be incorrect when used against resources derived from your custom
+traverser.
 
 If you've added a traverser, you can change how
 :meth:`~pyramid.request.Request.resource_url` generates a URL for a specific
-type of resource by adding a registerAdapter call for
-:class:`pyramid.interfaces.IContextURL` to your application:
+type of resource by adding a call to
+:meth:`pyramid.config.add_resource_url_adapter`.
+
+For example:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.interfaces import ITraverser
-   from zope.interface import Interface
-   from myapp.traversal import URLGenerator
+   from myapp.traversal import ResourceURLAdapter
    from myapp.resources import MyRoot
 
-   config.registry.registerAdapter(URLGenerator, (MyRoot, Interface),
-                                   IContextURL)
+   config.add_resource_url_adapter(ResourceURLAdapter, resource_iface=MyRoot)
 
-In the above example, the ``myapp.traversal.URLGenerator`` class will be used
-to provide services to :meth:`~pyramid.request.Request.resource_url` any time
-the :term:`context` passed to ``resource_url`` is of class
-``myapp.resources.MyRoot``.  The second argument in the ``(MyRoot,
-Interface)`` tuple represents the type of interface that must be possessed by
-the :term:`request` (in this case, any interface, represented by
-``zope.interface.Interface``).
+In the above example, the ``myapp.traversal.ResourceURLAdapter`` class will
+be used to provide services to :meth:`~pyramid.request.Request.resource_url`
+any time the :term:`resource` passed to ``resource_url`` is of the class
+``myapp.resources.MyRoot``.  The ``resource_iface`` argument ``MyRoot``
+represents the type of interface that must be possessed by the resource for
+this resource url factory to be found.  If the ``resource_iface`` argument is
+omitted, this resource url adapter will be used for *all* resources.
 
-The API that must be implemented by a class that provides
-:class:`~pyramid.interfaces.IContextURL` is as follows:
+The API that must be implemented by your a class that provides
+:class:`~pyramid.interfaces.IResourceURL` is as follows:
 
 .. code-block:: python
   :linenos:
 
-  from zope.interface import Interface
-
-  class IContextURL(Interface):
-      """ An adapter which deals with URLs related to a context.
+  class MyResourceURL(object):
+      """ An adapter which provides the virtual and physical paths of a
+          resource
       """
-      def __init__(self, context, request):
-          """ Accept the context and request """
-
-      def virtual_root(self):
-          """ Return the virtual root object related to a request and the
-          current context"""
-
-      def __call__(self):
-          """ Return a URL that points to the context """
+      def __init__(self, resource, request):
+          """ Accept the resource and request and set self.physical_path and 
+          self.virtual_path"""
+          self.virtual_path =  some_function_of(resource, request)
+          self.physical_path =  some_other_function_of(resource, request)
 
 The default context URL generator is available for perusal as the class
-:class:`pyramid.traversal.TraversalContextURL` in the `traversal module
+:class:`pyramid.traversal.ResourceURL` in the `traversal module
 <http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
 :term:`Pylons` GitHub Pyramid repository.
 
+See :meth:`pyramid.config.add_resource_url_adapter` for more information.
+
 .. index::
    single: IResponse
    single: special view responses
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index a27ef6af9..7d1c9217d 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -260,16 +260,21 @@ Minor Feature Additions
   http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
   more information about how to use the ``ignore`` argument to ``scan``.
 
-- Add :meth:`pyramid.config.Configurator.set_traverser` API method.  See
+- Add :meth:`pyramid.config.Configurator.add_traverser` API method.  See
   :ref:`changing_the_traverser` for more information.  This is not a new
   feature, it just provides an API for adding a traverser without needing to
   use the ZCA API.
 
+- Add :meth:`pyramid.config.Configurator.add_resource_url_adapter` API
+  method.  See :ref:`changing_resource_url` for more information.  This is
+  not a new feature, it just provides an API for adding a resource url
+  adapter without needing to use the ZCA API.
+
 - The :meth:`pyramid.config.Configurator.scan` method can now 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
+   http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
   more information about how to use the ``ignore`` argument to ``scan``.
 
 - Better error messages when a view callable returns a value that cannot be
@@ -291,6 +296,38 @@ Minor Feature Additions
   methods and attributes from within templates.  The value ``request`` is
   still available too, this is just an alternative.
 
+- A new interface was added: :class:`pyramid.interfaces.IResourceURL`.  An
+  adapter implementing its interface can be used to override resource URL
+  generation when :meth:`pyramid.request.Request.resource_url` is called.
+  This interface replaces the now-deprecated
+  ``pyramid.interfaces.IContextURL`` interface.
+
+- The dictionary passed to a resource's ``__resource_url__`` method (see
+  :ref:`overriding_resource_url_generation`) now contains an ``app_url`` key,
+  representing the application URL generated during
+  :meth:`pyramid.request.Request.resource_url`.  It represents a potentially
+  customized URL prefix, containing potentially custom scheme, host and port
+  information passed by the user to ``request.resource_url``.  It should be
+  used instead of ``request.application_url`` where necessary.
+
+- The :meth:`pyramid.request.Request.resource_url` API now accepts these
+  arguments: ``app_url``, ``scheme``, ``host``, and ``port``.  The app_url
+  argument can be used to replace the URL prefix wholesale during url
+  generation.  The ``scheme``, ``host``, and ``port`` arguments can be used
+  to replace the respective default values of ``request.application_url``
+  partially.
+
+- A new API named :meth:`pyramid.request.Request.resource_path` now exists.
+  It works like :meth:`pyramid.request.Request.resource_url`` but produces a
+  relative URL rather than an absolute one.
+
+- The :meth:`pyramid.request.Request.route_url` API now accepts these
+  arguments: ``_app_url``, ``_scheme``, ``_host``, and ``_port``.  The
+  ``_app_url`` argument can be used to replace the URL prefix wholesale
+  during url generation.  The ``_scheme``, ``_host``, and ``_port`` arguments
+  can be used to replace the respective default values of
+  ``request.application_url`` partially.
+
 Backwards Incompatibilities
 ---------------------------
 
@@ -360,6 +397,21 @@ Backwards Incompatibilities
   no negative affect because the implementation was broken for dict-based
   arguments.
 
+- The ``pyramid.interfaces.IContextURL`` interface has been deprecated.
+  People have been instructed to use this to register a resource url adapter
+  in the "Hooks" chapter to use to influence
+  :meth:`pyramid.request.Request.resource_url` URL generation for resources
+  found via custom traversers since Pyramid 1.0.
+
+  The interface still exists and registering such an adapter still works, but
+  this interface will be removed from the software after a few major Pyramid
+  releases.  You should replace it with an equivalent
+  :class:`pyramid.interfaces.IResourceURL` adapter, registered using the new
+  :meth:`pyramid.config.Configurator.add_resource_url_adapter` API.  A
+  deprecation warning is now emitted when a
+  ``pyramid.interfaces.IContextURL`` adapter is found when
+  :meth:`pyramid.request.Request.resource_url` is called.
+
 Documentation Enhancements
 --------------------------