> Read the latest version of this page
Edit me on GitHub

pyramid.url

Utility functions for dealing with URLs in pyramid

resource_url(context, request, *elements, query=None, anchor=None)[source]

Generate a string representing the absolute URL of the resource object based on the wsgi.url_scheme, HTTP_HOST or SERVER_NAME in the request, plus any SCRIPT_NAME. The overall result of this function is always a UTF-8 encoded string (never Unicode).

Note

Calling pyramid.Request.resource_url() can be used to achieve the same result as pyramid.url.resource_url().

Examples:

resource_url(context, request) =>

                           http://example.com/

resource_url(context, request, 'a.html') =>

                           http://example.com/a.html

resource_url(context, request, 'a.html', query={'q':'1'}) =>

                           http://example.com/a.html?q=1

resource_url(context, request, 'a.html', anchor='abc') =>

                           http://example.com/a.html#abc

Any positional arguments passed in as elements must be strings or Unicode objects. These will be joined by slashes and appended to the generated resource URL. Each of the elements passed in is URL-quoted before being appended; if any element is Unicode, it will converted to a UTF-8 bytestring before being URL-quoted.

Warning

if no elements arguments are specified, the resource URL will end with a trailing slash. If any elements are used, the generated URL will not end in trailing a slash.

If a keyword argument query is present, it will be used to compose a query string that will be tacked on to the end of the URL. The value of query must be a sequence of two-tuples or a data structure with an .items() method that returns a sequence of two-tuples (presumably a dictionary). This data structure will be turned into a query string per the documentation of pyramid.url.urlencode function. After the query data is turned into a query string, a leading ? is prepended, and the resulting string is appended to the generated URL.

Note

Python data structures that are passed as query which are sequences or dictionaries are turned into a string under the same rules as when run through urllib.urlencode() with the doseq argument equal to True. This means that sequences can be passed as values, and a k=v pair will be placed into the query string for each value.

If a keyword argument anchor is present, its string representation will be used as a named anchor in the generated URL (e.g. if anchor is passed as foo and the resource URL is http://example.com/resource/url, the resulting generated URL will be http://example.com/resource/url#foo).

Note

If anchor is passed as a string, it should be UTF-8 encoded. If anchor is passed as a Unicode object, it will be converted to UTF-8 before being appended to the URL. The anchor value is not quoted in any way before being appended to the generated URL.

If both anchor and query are specified, the anchor element will always follow the query element, e.g. http://example.com?foo=1#bar.

If the resource passed in has a __resource_url__ method, it will be used to generate the URL (scheme, host, port, path) that for the base resource which is operated upon by this function. See also Overriding Resource URL Generation.

Note

If the resource used is the result of a traversal, it must be location-aware. The resource can also be the context of a URL dispatch; contexts found this way do not need to be location-aware.

Note

If a ‘virtual root path’ is present in the request environment (the value of the WSGI environ key HTTP_X_VHM_ROOT), and the resource was obtained via traversal, the URL path will not include the virtual root prefix (it will be stripped off the left hand side of the generated URL).

Note

For backwards compatibility purposes, this function can also be imported as model_url, although doing so will emit a deprecation warning.

route_url(route_name, request, *elements, **kw)[source]

Generates a fully qualified URL for a named Pyramid route configuration.

Note

Calling pyramid.Request.route_url() can be used to achieve the same result as pyramid.url.route_url().

Use the route’s name as the first positional argument. Use a request object as the second positional argument. Additional positional arguments are appended to the URL as path segments after it is generated.

Use keyword arguments to supply values which match any dynamic path elements in the route definition. Raises a KeyError exception if the URL cannot be generated for any reason (not enough arguments, for example).

For example, if you’ve defined a route named “foobar” with the path {foo}/{bar}/*traverse:

route_url('foobar', request, foo='1')          => <KeyError exception>
route_url('foobar', request, foo='1', bar='2') => <KeyError exception>
route_url('foobar', request, foo='1', bar='2',
          traverse=('a','b'))                  => http://e.com/1/2/a/b
route_url('foobar', request, foo='1', bar='2',
          traverse='/a/b')                     => http://e.com/1/2/a/b

Values replacing :segment arguments can be passed as strings or Unicode objects. They will be encoded to UTF-8 and URL-quoted before being placed into the generated URL.

Values replacing *remainder arguments can be passed as strings or tuples of Unicode/string values. If a tuple is passed as a *remainder replacement value, its values are URL-quoted and encoded to UTF-8. The resulting strings are joined with slashes and rendered into the URL. If a string is passed as a *remainder replacement value, it is tacked on to the URL untouched.

If a keyword argument _query is present, it will be used to compose a query string that will be tacked on to the end of the URL. The value of _query must be a sequence of two-tuples or a data structure with an .items() method that returns a sequence of two-tuples (presumably a dictionary). This data structure will be turned into a query string per the documentation of pyramid.encode.urlencode() function. After the query data is turned into a query string, a leading ? is prepended, and the resulting string is appended to the generated URL.

Note

Python data structures that are passed as _query which are sequences or dictionaries are turned into a string under the same rules as when run through urllib.urlencode() with the doseq argument equal to True. This means that sequences can be passed as values, and a k=v pair will be placed into the query string for each value.

If a keyword argument _anchor is present, its string representation will be used as a named anchor in the generated URL (e.g. if _anchor is passed as foo and the route URL is http://example.com/route/url, the resulting generated URL will be http://example.com/route/url#foo).

Note

If _anchor is passed as a string, it should be UTF-8 encoded. If _anchor is passed as a Unicode object, it will be converted to UTF-8 before being appended to the URL. The anchor value is not quoted in any way before being appended to the generated URL.

If both _anchor and _query are specified, the anchor element will always follow the query element, e.g. http://example.com?foo=1#bar.

If a keyword _app_url is present, it will be used as the protocol/hostname/port/leading path prefix of the generated URL. For example, using an _app_url of http://example.com:8080/foo would cause the URL http://example.com:8080/foo/fleeb/flub to be returned from this function if the expansion of the route pattern associated with the route_name expanded to /fleeb/flub. If _app_url is not specified, the result of request.application_url will be used as the prefix (the default).

This function raises a KeyError if the URL cannot be generated due to missing replacement names. Extra replacement names are ignored.

If the route object which matches the route_name argument has a pregenerator, the *elements and **kw arguments arguments passed to this function might be augmented or changed.

current_route_url(request, *elements, **kw)[source]

Generates a fully qualified URL for a named Pyramid route configuration based on the ‘current route’.

This function supplements pyramid.url.route_url(). It presents an easy way to generate a URL for the ‘current route’ (defined as the route which matched when the request was generated).

The arguments to this function have the same meaning as those with the same names passed to pyramid.url.route_url(). It also understands an extra argument which route_url does not named _route_name.

The route name used to generate a URL is taken from either the _route_name keyword argument or the name of the route which is currently associated with the request if _route_name was not passed. Keys and values from the current request matchdict are combined with the kw arguments to form a set of defaults named newkw. Then route_url(route_name, request, *elements, **newkw) is called, returning a URL.

Examples follow.

If the ‘current route’ has the route pattern /foo/{page} and the current url path is /foo/1 , the matchdict will be {'page':'1'}. The result of current_route_url(request) in this situation will be /foo/1.

If the ‘current route’ has the route pattern /foo/{page} and the current current url path is /foo/1, the matchdict will be {'page':'1'}. The result of current_route_url(request, page='2') in this situation will be /foo/2.

Usage of the _route_name keyword argument: if our routing table defines routes /foo/{action} named ‘foo’ and /foo/{action}/{page} named fooaction, and the current url pattern is /foo/view (which has matched the /foo/{action} route), we may want to use the matchdict args to generate a URL to the fooaction route. In this scenario, current_url(request, _route_name='fooaction', page='5') Will return string like: /foo/view/5.

route_path(route_name, request, *elements, **kw)[source]

Generates a path (aka a ‘relative URL’, a URL minus the host, scheme, and port) for a named Pyramid route configuration.

Note

Calling pyramid.Request.route_path() can be used to achieve the same result as pyramid.url.route_path().

This function accepts the same argument as pyramid.url.route_url() and performs the same duty. It just omits the host, port, and scheme information in the return value; only the path, query parameters, and anchor data are present in the returned string.

For example, if you’ve defined a route named ‘foobar’ with the path /{foo}/{bar}, this call to route_path:

route_path('foobar', request, foo='1', bar='2')

Will return the string /1/2.

Note

Calling route_path('route', request) is the same as calling route_url('route', request, _app_url=''). route_path is, in fact, implemented in terms of route_url in just this way. As a result, any _app_url pass within the **kw values to route_path will be ignored.

static_url(path, request, **kw)[source]

Generates a fully qualified URL for a static asset. The asset must live within a location defined via the pyramid.config.Configurator.add_static_view() configuration declaration (see Serving Static Assets).

Note

Calling pyramid.Request.static_url() can be used to achieve the same result as pyramid.url.static_url().

Example:

static_url('mypackage:static/foo.css', request) =>

                        http://example.com/static/foo.css

The path argument points at a file or directory on disk which a URL should be generated for. The path may be either a relative path (e.g. static/foo.css) or a asset specification (e.g. mypackage:static/foo.css). A path may not be an absolute filesystem path (a ValueError will be raised if this function is supplied with an absolute path).

The request argument should be a request object.

The purpose of the **kw argument is the same as the purpose of the pyramid.url.route_url() **kw argument. See the documentation for that function to understand the arguments which you can provide to it. However, typically, you don’t need to pass anything as *kw when generating a static asset URL.

This function raises a ValueError if a static view definition cannot be found which matches the path specification.

urlencode(query, doseq=True)

An alternate implementation of Python’s stdlib urllib.urlencode function which accepts unicode keys and values within the query dict/sequence; all Unicode keys and values are first converted to UTF-8 before being used to compose the query string.

The value of query must be a sequence of two-tuples representing key/value pairs or an object (often a dictionary) with an .items() method that returns a sequence of two-tuples representing key/value pairs.

For minimal calling convention backwards compatibility, this version of urlencode accepts but ignores a second argument conventionally named doseq. The Python stdlib version behaves differently when doseq is False and when a sequence is presented as one of the values. This version always behaves in the doseq=True mode, no matter what the value of the second argument.

See the Python stdlib documentation for urllib.urlencode for more information.

Previous topic

pyramid.traversal

Next topic

pyramid.view

This Page