CHAPTER

SIXTYTWO

PYRAMID.URL

Utility functions for dealing with URLs in pyramid

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

This is a backwards compatibility function. Its result is the same as calling:

request.resource_url(resource, *elements, **kw)

See pyramid.request.Request.resource_url() for more information.

route_url(route_name, request, *elements, **kw)

This is a backwards compatibility function. Its result is the same as calling:

request.route_url(route_name, *elements, **kw)

See pyramid.request.Request.route_url() for more information.

current_route_url(request, *elements, **kw)

This is a backwards compatibility function. Its result is the same as calling:

request.current_route_url(*elements, **kw)

See pyramid.request.Request.current_route_url() for more information.

route_path(route_name, request, *elements, **kw)

This is a backwards compatibility function. Its result is the same as calling:

671

62. PYRAMID.URL

request.route_path(route_name, *elements, **kw)

See pyramid.request.Request.route_path() for more information.

current_route_path(request, *elements, **kw)

This is a backwards compatibility function. Its result is the same as calling:

request.current_route_path(*elements, **kw)

See pyramid.request.Request.current_route_path() for more information.

static_url(path, request, **kw)

This is a backwards compatibility function. Its result is the same as calling:

request.static_url(path, **kw)

See pyramid.request.Request.static_url() for more information.

static_path(path, request, **kw)

This is a backwards compatibility function. Its result is the same as calling:

request.static_path(path, **kw)

See pyramid.request.Request.static_path() for more information.

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.

672

CHAPTER

SIXTYTHREE

PYRAMID.VIEW

render_view_to_response(context, request, name=’‘, secure=True)

Call the view callable configured with a view configuration that matches the view name name registered against the specified context and request and return a response object. This function will return None if a corresponding view callable cannot be found (when no view configuration matches the combination of name / context / and request).

If secure‘ is True, and the view callable found is protected by a permission, the permission will be checked before calling the view function. If the permission check disallows view execution (based on the current authorization policy), a pyramid.httpexceptions.HTTPForbidden exception will be raised. The exception’s args attribute explains why the view access was disallowed.

If secure is False, no permission checking is done.

render_view_to_iterable(context, request, name=’‘, secure=True)

Call the view callable configured with a view configuration that matches the view name name registered against the specified context and request and return an iterable object which represents the body of a response. This function will return None if a corresponding view callable cannot be found (when no view configuration matches the combination of name / context / and request). Additionally, this function will raise a ValueError if a view function is found and called but the view function’s result does not have an app_iter attribute.

You can usually get the string representation of the return value of this function by calling

”.join(iterable), or just use pyramid.view.render_view() instead.

If secure is True, and the view is protected by a permission, the permission will be checked before the view function is invoked. If the permission check disallows view execution (based on the current authentication policy), a pyramid.httpexceptions.HTTPForbidden exception will be raised; its args attribute explains why the view access was disallowed.

If secure is False, no permission checking is done.

673

63. PYRAMID.VIEW

render_view(context, request, name=’‘, secure=True)

Call the view callable configured with a view configuration that matches the view name name registered against the specified context and request and unwind the view response’s app_iter (see View Callable Responses) into a single string. This function will return None if a corresponding view callable cannot be found (when no view configuration matches the combination of name / context / and request). Additionally, this function will raise a ValueError if a view function is found and called but the view function’s result does not have an app_iter attribute. This function will return None if a corresponding view cannot be found.

If secure is True, and the view is protected by a permission, the permission will be checked before the view is invoked. If the permission check disallows view execution (based on the current authorization policy), a pyramid.httpexceptions.HTTPForbidden exception will be raised; its args attribute explains why the view access was disallowed.

If secure is False, no permission checking is done.

is_response(ob)

Return True if ob implements the interface implied by View Callable Responses. False if not.

latex-warning.png

This function is deprecated as of Pyramid 1.1. New code should not use it. Instead, new code should use the pyramid.request.Request.is_response() method.

class view_config(name=(default), request_type=(default), for_=(default), permission=(default), route_name=(default), request_method=(default), request_param=(default), containment=(default), attr=(default), renderer=(default), wrapper=(default), xhr=(default), accept=(default), header=(default), path_info=(default), custom_predicates=(default), context=(default), decorator=(default), mapper=(default),

http_cache=(default), match_param=(default))

A function, class or method decorator which allows a developer to create view registrations nearer to a view callable definition than use imperative configuration to do the same.

For example, this code in a module views.py:

674

from resources import MyResource

@view_config(name=’my_view’, context=MyResource, permission=’read’, route_name=’site1’)

def my_view(context, request): return ’OK’

Might replace the following call to the pyramid.config.Configurator.add_view() method:

import views

from resources import MyResource

config.add_view(views.my_view, context=MyResource, name=’my_view’, permission=’read’, ’route_name=’site1’)

The following arguments are supported to pyramid.view.view_config: context, permission, name, request_type, route_name, request_method, request_param, containment, xhr, accept, header, path_info, custom_predicates, decorator, mapper, http_cache, and match_param.

The meanings of these arguments are the same as the arguments passed to pyramid.config.Configurator.add_view(). If any argument is left out, its default will be the equivalent add_view default.

See Adding View Configuration Using the @view_config Decorator for details about using view_config.

class view_defaults(name=(default), request_type=(default), for_=(default), permission=(default), route_name=(default), request_method=(default), request_param=(default), containment=(default), attr=(default), renderer=(default), wrapper=(default), xhr=(default), accept=(default), header=(default), path_info=(default), custom_predicates=(default), context=(default), decorator=(default), mapper=(default),

http_cache=(default), match_param=(default))

A class decorator which, when applied to a class, will provide defaults for all view configurations that use the class. This decorator accepts all the arguments accepted by pyramid.config.view_config, and each has the same meaning.

See @view_defaults Class Decorator for more information.

675

63. PYRAMID.VIEW

pend_slash=False)

An analogue of pyramid.view.view_config which registers a not found view.

The notfound_view_config constructor accepts most of the same arguments as the constructor of pyramid.view.view_config. It can be used in the same places, and behaves in largely the same way, except it always registers a not found exception view instead of a “normal” view.

Example:

from pyramid.view import notfound_view_config from pyramid.response import Response

notfound_view_config() def notfound(request):

return Response(’Not found, dude!’, status=’404 Not Found’)

All arguments except append_slash have the same meaning as pyramid.view.view_config() and each predicate argument restricts the set of circumstances under which this notfound view will be invoked.

If append_slash is True, when the notfound view is invoked, and the current path info does not end in a slash, the notfound logic will attempt to find a route that matches the request’s path info suffixed with a slash. If such a route exists, Pyramid will issue a redirect to the URL implied by the route; if it does not, Pyramid will return the result of the view callable provided as view, as normal.

See Changing the Not Found View for detailed usage information.

latex-note.png

This class is new as of Pyramid 1.3.

676

tom_predicates=(default), decorator=(default), map-

per=(default), match_param=(default))

An analogue of pyramid.view.view_config which registers a forbidden view.

The forbidden_view_config constructor accepts most of the same arguments as the constructor of pyramid.view.view_config. It can be used in the same places, and behaves in largely the same way, except it always registers a forbidden exception view instead of a “normal” view.

Example:

from pyramid.view import forbidden_view_config from pyramid.response import Response

forbidden_view_config() def notfound(request):

return Response(’You are not allowed’, status=’401 Unauthorized’)

All have the same meaning as pyramid.view.view_config() and each predicate argument restricts the set of circumstances under which this notfound view will be invoked.

See Changing the Forbidden View for detailed usage information.

latex-note.png

This class is new as of Pyramid 1.3.

class static(root_dir, cache_max_age=3600, package_name=None)

Backwards compatibility alias for pyramid.static.static_view; it overrides that class’ constructor to pass use_subpath=True by default. This class is deprecated as of Pyramid 1.1. Use pyramid.static.static_view instead (probably with a use_subpath=True argument).

677

63. PYRAMID.VIEW

678