'Generates a fully qualified URL for a named :app:`Pyramid`
:term:`route configuration`.
Use the route\'s ``name`` as the first positional argument.
Additional positional arguments (``*elements``) 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 :exc:`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``::
request.route_url(\'foobar\',
foo=\'1\')             => <KeyError exception>
request.route_url(\'foobar\',
foo=\'1\',
bar=\'2\')             => <KeyError exception>
request.route_url(\'foobar\',
foo=\'1\',
bar=\'2\',
traverse=(\'a\',\'b\'))  => http://e.com/1/2/a/b
request.route_url(\'foobar\',
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
after being URL-quoted-except-for-embedded-slashes.
If no ``_query`` keyword argument is provided, the request query string
will be returned in the URL. If it is present, it will be used to
compose a query string that will be tacked on to the end of the URL,
replacing any request query string.  The value of ``_query`` may 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 :func:`pyramid.url.urlencode` function.  This will
produce a query string in the ``x-www-form-urlencoded`` format.  A
non-``x-www-form-urlencoded`` query string may be used by passing a
*string* value as ``_query`` in which case it will be URL-quoted
(e.g. query="foo bar" will become "foo%20bar").  However, the result
will not need to be in ``k=v`` form as required by
``x-www-form-urlencoded``.  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 :func:`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 quoted per :rfc:`3986#section-3.5` and 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.
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 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 ``http://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 ``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
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).
If both ``_app_url`` and any of ``_scheme``, ``_host``, or ``_port``
are passed, ``_app_url`` takes precedence and any values passed for
``_scheme``, ``_host``, and ``_port`` will be ignored.
This function raises a :exc:`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 :term:`pregenerator`, the ``*elements`` and ``**kw``
arguments passed to this function might be augmented or changed.
.. versionchanged:: 1.5
Allow the ``_query`` option to be a string to enable alternative
encodings.
The ``_anchor`` option will be escaped instead of using
its raw string representation.
.. versionchanged:: 1.9
If ``_query`` or ``_anchor`` are falsey (such as ``None`` or an
empty string) they will not be included in the generated url.'

def route_url(self, route_name, *elements, **kw):

    try:
        reg = self.registry
    except AttributeError:
        reg = get_current_registry()
    mapper = reg.getUtility(IRoutesMapper)
    route = mapper.get_route(route_name)
    if (route is None):
        raise KeyError(('No    such    route    named    %s' % route_name))
    if (route.pregenerator is not None):
        (elements, kw) = route.pregenerator(self, elements, kw)
    (app_url, qs, anchor) = parse_url_overrides(self, kw)
    path = route.generate(kw)
    if elements:
        suffix = _join_elements(elements)
        if (not path.endswith('/')):
            suffix = ('/' + suffix)
    else:
        suffix = ''
    return ((((app_url + path) + suffix) + qs) + anchor)
