From fb90f0166728af40142ed9a31039d26ca3f97c73 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 14 Aug 2011 04:58:34 -0400 Subject: - 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. --- docs/narr/resources.rst | 92 +++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 48 deletions(-) (limited to 'docs/narr/resources.rst') 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 -- cgit v1.2.3