diff options
| -rw-r--r-- | docs/narr/resources.rst | 29 | ||||
| -rw-r--r-- | docs/whatsnew-1.3.rst | 2 | ||||
| -rw-r--r-- | pyramid/url.py | 23 |
3 files changed, 34 insertions, 20 deletions
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 83734be9f..a24c44f29 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -303,13 +303,22 @@ The ``__resource_url__`` hook is passed two arguments: ``request`` and two keys: ``physical_path`` - The "physical path" computed for the resource, as defined by - ``pyramid.traversal.resource_path(resource)``. + A string representing the "physical path" computed for the resource, as + defined by ``pyramid.traversal.resource_path(resource)``. It will begin + and end with a slash. ``virtual_path`` - The "virtual path" computed for the resource, as defined by - :ref:`virtual_root_support`. This will be identical to the physical path - if virtual rooting is not enabled. + A string representing the "virtual path" computed for the resource, as + defined by :ref:`virtual_root_support`. This will be identical to the + physical path if virtual rooting is not enabled. It will begin and end + with a slash. + +``app_url`` + A string representing the application URL generated during + ``request.resource_url``. It will not end with a slash. 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 preferred over use of ``request.application_url``. The ``__resource_url__`` method of a resource should return a string representing a URL. If it cannot override the default, it should return @@ -322,16 +331,16 @@ Here's an example ``__resource_url__`` method. class Resource(object): def __resource_url__(self, request, info): - return request.application_url + info['virtual_path'] + return info['app_url'] + info['virtual_path'] The above example actually just generates and returns the default URL, which -would have been what was returned anyway, but your code can perform arbitrary -logic as necessary. For example, your code may wish to override the hostname -or port number of the generated URL. +would have been what was generated by the default ``resource_url`` machinery, +but your code can perform arbitrary logic as necessary. For example, your +code may wish to override the hostname 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 +anchor elements (only path elements) to work with :meth:`~pyramid.request.Request.resource_url`. .. index:: diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index 7d1c9217d..674b16e11 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -274,7 +274,7 @@ Minor Feature Additions ``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 diff --git a/pyramid/url.py b/pyramid/url.py index d1c1b6f42..efcf241b7 100644 --- a/pyramid/url.py +++ b/pyramid/url.py @@ -160,13 +160,18 @@ class URLMethodsMixin(object): element will always follow the query element, e.g. ``http://example.com?foo=1#bar``. - If any of ``_scheme``, ``_host``, or ``_port`` is passed and is - non-``None``, the provided value will replace the named portion in - the generated URL. If ``_scheme`` is passed as ``https``, and + If any of the keyword arguments ``_scheme``, ``_host``, or ``_port`` + is passed and is non-``None``, the provided value will replace the + named portion in the generated URL. For example, if you pass + ``_host='foo.com'``, and the URL that would have been generated + without the host replacement is ``http://example.com/a``, the result + will be ``https://foo.com/a``. + + Note that if ``_scheme`` is passed as ``https``, and ``_port`` is not + passed, the ``_port`` value is assumed to have been passed as + ``443``. Likewise, if ``_scheme`` is passed as ``http`` and ``_port`` is not passed, the ``_port`` value is assumed to have been - passed as ``443``. Likewise, if ``_scheme`` is passed as ``http`` - and ``_port`` is not passed, the ``_port`` value is assumed to have - been passed as ``80``. To avoid this behavior, always explicitly pass + passed as ``80``. To avoid this behavior, always explicitly pass ``_port`` whenever you pass ``_scheme``. If a keyword ``_app_url`` is present, it will be used as the @@ -362,9 +367,9 @@ class URLMethodsMixin(object): If any of the keyword arguments ``scheme``, ``host``, or ``port`` is passed and is non-``None``, the provided value will replace the named portion in the generated URL. For example, if you pass - ``scheme='https'``, and the URL that would be generated without the - scheme replacement is ``http://foo.com``, the result will be - ``https://foo.com``. + ``host='foo.com'``, and the URL that would have been generated + without the host replacement is ``http://example.com/a``, the result + will be ``https://foo.com/a``. If ``scheme`` is passed as ``https``, and an explicit ``port`` is not passed, the ``port`` value is assumed to have been passed as ``443``. |