- 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.

7 files changed, 97 insertions, 99 deletions

diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index e609a3eab..c8508f1b5 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -165,7 +165,8 @@ Instead of representing a URL prefix, the ``name`` argument of a call to
 *URL*.  Each of examples we've seen so far have shown usage of the ``name``
 argument as a URL prefix.  However, when ``name`` is a *URL*, static assets
 can be served from an external webserver.  In this mode, the ``name`` is used
-as the URL prefix when generating a URL using :func:`pyramid.url.static_url`.
+as the URL prefix when generating a URL using
+:meth:`pyramid.request.Request.static_url`.
 
 For example, :meth:`~pyramid.config.Configurator.add_static_view` may
 be fed a ``name`` argument which is ``http://example.com/images``:
@@ -179,13 +180,13 @@ be fed a ``name`` argument which is ``http://example.com/images``:
 
 Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with
 a ``name`` argument that is the URL ``http://example.com/images``, subsequent
-calls to :func:`~pyramid.url.static_url` with paths that start with the
-``path`` argument passed to
+calls to :meth:`~pyramid.request.Request.static_url` with paths that start
+with the ``path`` argument passed to
 :meth:`~pyramid.config.Configurator.add_static_view` will generate a URL
 something like ``http://example.com/images/logo.png``.  The external
 webserver listening on ``example.com`` must be itself configured to respond
-properly to such a request.  The :func:`~pyramid.url.static_url` API is
-discussed in more detail later in this chapter.
+properly to such a request.  The :meth:`~pyramid.request.Request.static_url`
+API is discussed in more detail later in this chapter.
 
 .. index::
    single: generating static asset urls
@@ -199,9 +200,9 @@ Generating Static Asset URLs
 
 When a :meth:`~pyramid.config.Configurator.add_static_view` method is used to
 register a static asset directory, a special helper API named
-:func:`pyramid.url.static_url` can be used to generate the appropriate URL
-for an asset that lives in one of the directories named by the static
-registration ``path`` attribute.
+:meth:`pyramid.request.Request.static_url` can be used to generate the
+appropriate URL for an asset that lives in one of the directories named by
+the static registration ``path`` attribute.
 
 For example, let's assume you create a set of static declarations like so:
 
@@ -219,18 +220,17 @@ visits a URL which begins with ``/static1``, and the assets in the
 visits a URL which begins with ``/static2``.
 
 You needn't generate the URLs to static assets "by hand" in such a
-configuration.  Instead, use the :func:`~pyramid.url.static_url` API to
-generate them for you.  For example:
+configuration.  Instead, use the :meth:`~pyramid.request.Request.static_url`
+API to generate them for you.  For example:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.url import static_url
    from pyramid.chameleon_zpt import render_template_to_response
 
    def my_view(request):
-       css_url = static_url('mypackage:assets/1/foo.css', request)
-       js_url = static_url('mypackage:assets/2/foo.js', request)
+       css_url = request.static_url('mypackage:assets/1/foo.css')
+       js_url = request.static_url('mypackage:assets/2/foo.js')
        return render_template_to_response('templates/my_template.pt',
                                           css_url = css_url,
                                           js_url = js_url)
@@ -240,17 +240,18 @@ If the request "application URL" of the running system is
 ``http://example.com/static1/foo.css``.  The ``js_url`` generated
 above would be ``http://example.com/static2/foo.js``.
 
-One benefit of using the :func:`~pyramid.url.static_url` function rather than
-constructing static URLs "by hand" is that if you need to change the ``name``
-of a static URL declaration, the generated URLs will continue to resolve
-properly after the rename.
+One benefit of using the :meth:`~pyramid.request.Request.static_url` function
+rather than constructing static URLs "by hand" is that if you need to change
+the ``name`` of a static URL declaration, the generated URLs will continue to
+resolve properly after the rename.
 
-URLs may also be generated by :func:`~pyramid.url.static_url` to static assets
-that live *outside* the :app:`Pyramid` application.  This will happen when
-the :meth:`~pyramid.config.Configurator.add_static_view` API associated with
-the path fed to :func:`~pyramid.url.static_url` is a *URL* instead of a view
-name.  For example, the ``name`` argument may be ``http://example.com`` while
-the the ``path`` given may be ``mypackage:images``:
+URLs may also be generated by :meth:`~pyramid.request.Request.static_url` to
+static assets that live *outside* the :app:`Pyramid` application.  This will
+happen when the :meth:`~pyramid.config.Configurator.add_static_view` API
+associated with the path fed to :meth:`~pyramid.request.Request.static_url`
+is a *URL* instead of a view name.  For example, the ``name`` argument may be
+``http://example.com`` while the the ``path`` given may be
+``mypackage:images``:
 
 .. code-block:: python
    :linenos:
@@ -265,14 +266,14 @@ assets which begin with ``mypackage:images`` will be prefixed with
 .. code-block:: python
    :linenos:
 
-   static_url('mypackage:images/logo.png', request)
+   request.static_url('mypackage:images/logo.png')
    # -> http://example.com/images/logo.png
 
-Using :func:`~pyramid.url.static_url` in conjunction with a
+Using :meth:`~pyramid.request.Request.static_url` in conjunction with a
 :meth:`~pyramid.configuration.Configurator.add_static_view` makes it possible
 to put static media on a separate webserver during production (if the
-``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is a
-URL), while keeping static media package-internal and served by the
+``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is
+a URL), while keeping static media package-internal and served by the
 development webserver during development (if the ``name`` argument to
 :meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix).  To
 create such a circumstance, we suggest using the
@@ -298,8 +299,9 @@ dispatch`, you may want static assets to only be available as a fallback if
 no previous route matches.  Alternately, you might like to serve a particular
 static asset manually, because its download requires authentication.
 
-Note that you cannot use the :func:`~pyramid.url.static_url` API to generate
-URLs against assets made accessible by registering a custom static view.
+Note that you cannot use the :meth:`~pyramid.request.Request.static_url` API
+to generate URLs against assets made accessible by registering a custom
+static view.
 
 Root-Relative Custom Static View (URL Dispatch Only)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 97004d2b8..1c9d0b15c 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -532,7 +532,7 @@ Now you can readily use Pyramid's APIs for generating URLs:
 
 .. code-block:: python
 
-   route_url('verify', env['request'], code='1337')
+   env['request'].route_url('verify', code='1337')
    # will return 'https://example.com/prefix/verify/1337'
 
 Cleanup
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 50758f327..df5339c8a 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -468,17 +468,18 @@ when the application :term:`root factory` returned an instance of the
 
 .. _changing_resource_url:
 
-Changing How :mod:`pyramid.url.resource_url` Generates a URL
-------------------------------------------------------------
+Changing How :meth:`pyramid.request.Request.resource_url` Generates a URL
+-------------------------------------------------------------------------
 
 When you add a traverser as described in :ref:`changing_the_traverser`, it's
-often convenient to continue to use the :func:`pyramid.url.resource_url` API.
-However, since the way traversal is done will have been modified, the URLs it
-generates by default may be incorrect.
+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.
 
 If you've added a traverser, you can change how
-:func:`~pyramid.url.resource_url` generates a URL for a specific type of
-resource by adding a registerAdapter call for
+: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:
 
 .. code-block:: python
@@ -493,8 +494,8 @@ resource by adding a registerAdapter call for
                                    IContextURL)
 
 In the above example, the ``myapp.traversal.URLGenerator`` class will be used
-to provide services to :func:`~pyramid.url.resource_url` any time the
-:term:`context` passed to ``resource_url`` is of class
+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
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
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index aa36b4455..ef875c8f0 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -565,6 +565,6 @@ See the :ref:`view_config_chapter` chapter for detailed information about
 The :mod:`pyramid.traversal` module contains API functions that deal with
 traversal, such as traversal invocation from within application code.
 
-The :func:`pyramid.url.resource_url` function generates a URL when given a
-resource retrieved from a resource tree.
+The :meth:`pyramid.request.Request.resource_url` method generates a URL when
+given a resource retrieved from a resource tree.
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index c0197743b..00d36cc76 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -765,20 +765,19 @@ Or provide the literal string ``/`` as the pattern:
 Generating Route URLs
 ---------------------
 
-Use the :func:`pyramid.url.route_url` function to generate URLs based on
-route patterns.  For example, if you've configured a route with the ``name``
-"foo" and the ``pattern`` "{a}/{b}/{c}", you might do this.
+Use the :meth:`pyramid.request.Request.route_url` method to generate URLs
+based on route patterns.  For example, if you've configured a route with the
+``name`` "foo" and the ``pattern`` "{a}/{b}/{c}", you might do this.
 
 .. ignore-next-block
 .. code-block:: python
    :linenos:
 
-   from pyramid.url import route_url
-   url = route_url('foo', request, a='1', b='2', c='3')
+   url = request.route_url('foo', a='1', b='2', c='3')
 
 This would return something like the string ``http://example.com/1/2/3`` (at
 least if the current protocol and hostname implied ``http://example.com``).
-See the :func:`~pyramid.url.route_url` API documentation for more
+See the :meth:`~pyramid.request.Request.route_url` API documentation for more
 information.
 
 .. index::
@@ -1122,8 +1121,8 @@ In the above configuration, the ``show_users`` route will have an effective
 route pattern of ``/users/show``, instead of ``/show`` because the
 ``route_prefix`` argument will be prepended to the pattern.  The route will
 then only match if the URL path is ``/users/show``, and when the
-:func:`pyramid.url.route_url` function is called with the route name
-``show_users``, it will generate a URL with that same path.
+:meth:`pyramid.request.Request.route_url` function is called with the route
+name ``show_users``, it will generate a URL with that same path.
 
 Route prefixes are recursive, so if a callable executed via an include itself
 turns around and includes another callable, the second-level route prefix
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index 5679cc2e2..ddbf1fb4d 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -101,8 +101,8 @@ the WSGI environ named ``HTTP_X_VHM_ROOT`` with a value that is the absolute
 pathname to the resource object in the resource tree that should behave as
 the "root" resource.  As a result, the traversal machinery will respect this
 value during traversal (prepending it to the PATH_INFO before traversal
-starts), and the :func:`pyramid.url.resource_url` API will generate the
-"correct" virtually-rooted URLs.
+starts), and the :meth:`pyramid.request.Request.resource_url` API will
+generate the "correct" virtually-rooted URLs.
 
 An example of an Apache ``mod_proxy`` configuration that will host the
 ``/cms`` subobject as ``http://www.example.com/`` using this facility