Python Pyramid - Application Configuration

The Pyramid application object has an application registry that stores mappings of view functions to routes, and other application-specific component registrations. The Configurator class is used to build the application registry.

The Configurator life cycle is managed by a context manager that returns an application object.

with Configurator(settings=settings) as config:
   #configuration methods
   app = config.make_wsgi_app()

The Configurator class defines the following important methods to customize the application −

add_route()

This method registers a route for URL dispatch. Following arguments are used −

  • name − The first required positional argument must be a unique name for the route. The name is used to identify the route when registering views or generating URLs.

  • pattern − The second required positional argument is a string representing the URL path optionally containing variable placeholders for parsing the variable data from the URL. The placeholders are surrounded by curly brackets. For example, "/students/{id}".

  • request_method − The value can be one of "GET", "POST", "HEAD", "DELETE", "PUT". Requests only of this type will be matched against the route.

add_view()

This method adds a view configuration to the application registry. It binds a view function to the route_name present in the configuration. The arguments required are −

  • view − The name of a view function.

  • route_name − A string that must match the name of a route configuration declaration.

  • request_method − Either a string (such as "GET", "POST", "PUT", "DELETE", "HEAD" or "OPTIONS") representing an HTTP REQUEST_METHOD, or a tuple containing one or more of these strings.

add_static_view()

This method adds a view used to render static assets such as images and CSS files, and uses the following arguments −

  • name − This argument is a string representing an application-relative local URL prefix, or a full URL.

  • Path − This argument represents the path on disk where the static files reside. Its value can be an absolute or a package-relative path.

This method in turn calls the add_route() method of Configurator object.

add_notfound_view()

This method adds a view to be executed when a matching view cannot be found for the current request. The following code shows an example −

from pyramid.config import Configurator
from pyramid.response import Response

def notfound(request):
   return Response('Not Found', status='404 Not Found')
   
config.add_notfound_view(notfound)

add_forbidden_view()

Configures the application registry so as to define a view to be executed when there is HTTPForbidden exception raised. The argument list contains a reference to a function that returns a 403 status response. If no argument is provided, the registry adds default_exceptionresponse_view().

add_exception_view()

This method causes addition of an exception view function to the configuration, for the specified exception.

make_wsgi_app()

This method returns a Pyramid WSGI application object.

scan()

This is a wrapper for registering views. It imports all application modules looking for @view_config decorators.

For each one, it calls config.add_view(view) with the same keyword arguments. A call to scan() function performs the scan of the package and all the subpackages for all the decorations.

A typical sequence of statements that performs configuration of application registry is as in the following code snippet −

from pyramid.config import Configurator

with Configurator() as config:
   config.add_route('hello', '/')
   config.add_view(hello_world, route_name='hello')
   app = config.make_wsgi_app()

This approach towards configuration of the application is called imperative configuration. Pyramid provides another approach towards configuration, called as decorative configuration.

Declarative Configuration

Sometimes, it becomes difficult to do the configuration by imperative code, especially when the application code is spread across many files. The declarative configuration is a convenient approach. The pyramid.view model defines view_config – a function, class or method decorator - that allows the view registrations very close to the definition of view function itself.

Two important arguments are provided to @view_config() decorator. They are route_name and request_method. They bear same explanation as in add_route() method of Configurator class. The function just below it is decorated so that it is bound to the route added to the registry of the application object.

Give below is the example of declarative configuration of hello_world() view function −

from pyramid.response import Response
from pyramid.view import view_config

@view_config(route_name='hello', request_method='GET')
def hello_world(request):
   return Response('Hello World!')

The view_config decorator adds an attribute to the hello_world() function, making it available for a scan to find it later.

Example

The combination of configuration decoration and the invocation of a scan is collectively known as declarative configuration. Following code configures the application registry with declarative approach.

The scan() function discovers the routes and their mapped views, so that there is the need to add imperative configuration statements.

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response
from pyramid.view import view_config

@view_config(route_name='hello', request_method='GET')
def hello_world(request):
   return Response('Hello World!')
   
if __name__ == '__main__':
   with Configurator() as config:
      config.add_route('hello', '/')
      config.scan()
      app = config.make_wsgi_app()
   server = make_server('0.0.0.0', 6543, app)
   server.serve_forever()

The scanner translates the arguments to view_config into a call to the pyramid.config.Configurator.add_view() method, so that the action is equivalent to the following statement −

config.add_view(hello_world, route_name='hello', request_method='GET')

Output

After the above program is run, the WSGI server starts. When the browser visits the link http://localhost:6543/, the "Hello World" message is rendered as before.

Config
Advertisements