- The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and

  ``current_route_url`` functions in the ``pyramid.url`` package now delegate
  to a method on the request they've been passed, instead of the other way
  around.  The pyramid.request.Request object now inherits from a mixin named
  pyramid.url.URLMethodsMixin to make this possible, and all url/path
  generation logic is embedded in this mixin.

- Narrative and API documentation which used the ``route_url``,
  ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url``
  functions in the ``pyramid.url`` package have now been changed to use
  eponymous methods of the request instead.

1 files changed, 44 insertions, 48 deletions

diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 0e0d00020..9335906a0 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -45,8 +45,8 @@ Also:
 - A resource is exposed to :term:`view` code as the :term:`context` of a
   view.
 
-- Various helpful :app:`Pyramid` API methods expect a resource as an
-  argument (e.g. :func:`~pyramid.url.resource_url` and others).
+- Various helpful :app:`Pyramid` API methods expect a resource as an argument
+  (e.g. :meth:`~pyramid.request.Request.resource_url` and others).
 
 .. index::
    single: resource tree
@@ -160,14 +160,14 @@ resource in the resource tree, you will eventually come to the root resource,
 just like if you keep executing the ``cd ..`` filesystem command, eventually
 you will reach the filesystem root directory.
 
-.. warning:: If your root resource has a ``__name__`` argument
-   that is not ``None`` or the empty string, URLs returned by the
-   :func:`~pyramid.url.resource_url` function and paths generated by
-   the :func:`~pyramid.traversal.resource_path` and
-   :func:`~pyramid.traversal.resource_path_tuple` APIs will be
-   generated improperly.  The value of ``__name__`` will be prepended
-   to every path and URL generated (as opposed to a single leading
-   slash or empty tuple element).
+.. warning:: If your root resource has a ``__name__`` argument that is not
+   ``None`` or the empty string, URLs returned by the
+   :func:`~pyramid.request.Request.resource_url` function and paths generated
+   by the :func:`~pyramid.traversal.resource_path` and
+   :func:`~pyramid.traversal.resource_path_tuple` APIs will be generated
+   improperly.  The value of ``__name__`` will be prepended to every path and
+   URL generated (as opposed to a single leading slash or empty tuple
+   element).
 
 .. sidebar::  Using :mod:`pyramid_traversalwrapper`
 
@@ -192,7 +192,8 @@ you will reach the filesystem root directory.
 
 Applications which use tree-walking :app:`Pyramid` APIs require
 location-aware resources.  These APIs include (but are not limited to)
-:func:`~pyramid.url.resource_url`, :func:`~pyramid.traversal.find_resource`,
+:meth:`~pyramid.request.Request.resource_url`,
+:func:`~pyramid.traversal.find_resource`,
 :func:`~pyramid.traversal.find_root`,
 :func:`~pyramid.traversal.find_interface`,
 :func:`~pyramid.traversal.resource_path`,
@@ -215,23 +216,23 @@ Generating The URL Of A Resource
 --------------------------------
 
 If your resources are :term:`location` aware, you can use the
-:func:`pyramid.url.resource_url` API to generate a URL for the resource.
-This URL will use the resource's position in the parent tree to create a
-resource path, and it will prefix the path with the current application URL
-to form a fully-qualified URL with the scheme, host, port, and path.  You can
-also pass extra arguments to :func:`~pyramid.url.resource_url` to influence
-the generated URL.
+:meth:`pyramid.request.Request.resource_url` API to generate a URL for the
+resource.  This URL will use the resource's position in the parent tree to
+create a resource path, and it will prefix the path with the current
+application URL to form a fully-qualified URL with the scheme, host, port,
+and path.  You can also pass extra arguments to
+:meth:`~pyramid.request.Request.resource_url` to influence the generated URL.
 
-The simplest call to :func:`~pyramid.url.resource_url` looks like this:
+The simplest call to :meth:`~pyramid.request.Request.resource_url` looks like
+this:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.url import resource_url
-   url = resource_url(resource, request)
+   url = request.resource_url(resource, request)
 
-The ``request`` passed to ``resource_url`` in the above example is an
-instance of a :app:`Pyramid` :term:`request` object.
+The ``request`` in the above example is an instance of a :app:`Pyramid`
+:term:`request` object.
 
 If the resource referred to as ``resource`` in the above example was the root
 resource, and the host that was used to contact the server was
@@ -240,51 +241,46 @@ However, if the resource was a child of the root resource named ``a``, the
 generated URL would be ``http://example.com/a/``.
 
 A slash is appended to all resource URLs when
-:func:`~pyramid.url.resource_url` is used to generate them in this simple
-manner, because resources are "places" in the hierarchy, and URLs are meant
-to be clicked on to be visited.  Relative URLs that you include on HTML pages
-rendered as the result of the default view of a resource are more
+:meth:`~pyramid.request.Request.resource_url` is used to generate them in
+this simple manner, because resources are "places" in the hierarchy, and URLs
+are meant to be clicked on to be visited.  Relative URLs that you include on
+HTML pages rendered as the result of the default view of a resource are more
 apt to be relative to these resources than relative to their parent.
 
-You can also pass extra elements to :func:`~pyramid.url.resource_url`:
+You can also pass extra elements to
+:meth:`~pyramid.request.Request.resource_url`:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.url import resource_url
-   url = resource_url(resource, request, 'foo', 'bar')
+   url = request.resource_url(resource, 'foo', 'bar')
 
 If the resource referred to as ``resource`` in the above example was the root
 resource, and the host that was used to contact the server was
 ``example.com``, the URL generated would be ``http://example.com/foo/bar``.
 Any number of extra elements can be passed to
-:func:`~pyramid.url.resource_url` as extra positional arguments.  When extra
-elements are passed, they are appended to the resource's URL.  A slash is not
-appended to the final segment when elements are passed.
+:meth:`~pyramid.request.Request.resource_url` as extra positional arguments.
+When extra elements are passed, they are appended to the resource's URL.  A
+slash is not appended to the final segment when elements are passed.
 
 You can also pass a query string:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.url import resource_url
-   url = resource_url(resource, request, query={'a':'1'})
+   url = request.resource_url(resource, query={'a':'1'})
 
 If the resource referred to as ``resource`` in the above example was the root
 resource, and the host that was used to contact the server was
 ``example.com``, the URL generated would be ``http://example.com/?a=1``.
 
 When a :term:`virtual root` is active, the URL generated by
-:func:`~pyramid.url.resource_url` for a resource may be "shorter" than its
-physical tree path.  See :ref:`virtual_root_support` for more information
-about virtually rooting a resource.
-
-The shortcut method of the :term:`request` named
-:meth:`pyramid.request.Request.resource_url` can be used instead of
-:func:`~pyramid.url.resource_url` to generate a resource URL.
+:meth:`~pyramid.request.Request.resource_url` for a resource may be "shorter"
+than its physical tree path.  See :ref:`virtual_root_support` for more
+information about virtually rooting a resource.
 
 For more information about generating resource URLs, see the documentation
-for :func:`pyramid.url.resource_url`.
+for :meth:`pyramid.request.Request.resource_url`.
 
 .. index::
    pair: resource URL generation; overriding
@@ -295,14 +291,14 @@ Overriding Resource URL Generation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If a resource object implements a ``__resource_url__`` method, this method
-will be called when :func:`~pyramid.url.resource_url` is called to generate a
-URL for the resource, overriding the default URL returned for the resource by
-:func:`~pyramid.url.resource_url`.
+will be called when :meth:`~pyramid.request.Request.resource_url` is called
+to generate a URL for the resource, overriding the default URL returned for
+the resource by :meth:`~pyramid.request.Request.resource_url`.
 
 The ``__resource_url__`` hook is passed two arguments: ``request`` and
 ``info``.  ``request`` is the :term:`request` object passed to
-:func:`~pyramid.url.resource_url`.  ``info`` is a dictionary with two
-keys:
+:meth:`~pyramid.request.Request.resource_url`.  ``info`` is a dictionary with
+two keys:
 
 ``physical_path``
    The "physical path" computed for the resource, as defined by
@@ -334,7 +330,7 @@ or port number of the generated URL.
 Note that the URL generated by ``__resource_url__`` should be fully
 qualified, should end in a slash, and should not contain any query string or
 anchor elements (only path elements) to work best with
-:func:`~pyramid.url.resource_url`.
+:meth:`~pyramid.request.Request.resource_url`.
 
 .. index::
    single: resource path generation