Startup

When you cause a Pyramid application to start up in a console window, you’ll see something much like this show up on the console:

$ paster serve myproject/MyProject.ini
Starting server in PID 16601.
serving on 0.0.0.0:6543 view at http://127.0.0.1:6543

This chapter explains what happens between the time you press the “Return” key on your keyboard after typing paster serve myproject/MyProject.ini and the time the line serving on 0.0.0.0:6543 ... is output to your console.

The Startup Process

The easiest and best-documented way to start and serve a Pyramid application is to use the paster serve command against a PasteDeploy .ini file. This uses the .ini file to infer settings and starts a server listening on a port. For the purposes of this discussion, we’ll assume that you are using this command to run your Pyramid application.

Here’s a high-level time-ordered overview of what happens when you press return after running paster serve development.ini.

  1. The PasteDeploy paster command is invoked under your shell with the arguments serve and development.ini. As a result, the PasteDeploy framework recognizes that it is meant to begin to run and serve an application using the information contained within the development.ini file.

  2. The PasteDeploy framework finds a section named either [app:main], [pipeline:main], or [composite:main] in the .ini file. This section represents the configuration of a WSGI application that will be served. If you’re using a simple application (e.g. [app:main]), the application entry point or dotted Python name will be named on the use= line within the section’s configuration. If, instead of a simple application, you’re using a WSGI pipeline (e.g. a [pipeline:main] section), the application named on the “last” element will refer to your Pyramid application. If instead of a simple application or a pipeline, you’re using a Paste “composite” (e.g. [composite:main]), refer to the documentation for that particular composite to understand how to make it refer to your Pyramid application.

  3. The application’s constructor (named by the entry point reference or dotted Python name on the use= line of the section representing your Pyramid application) is passed the key/value parameters mentioned within the section in which it’s defined. The constructor is meant to return a router instance, which is a WSGI application.

    For Pyramid applications, the constructor will be a function named main in the __init__.py file within the package in which your application lives. If this function succeeds, it will return a Pyramid router instance. Here’s the contents of an example __init__.py module:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    from pyramid.config import Configurator
from myproject.resources import Root

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    config = Configurator(root_factory=Root, settings=settings)
    config.add_view('myproject.views.my_view',
                    context='myproject.resources.Root',
                    renderer='myproject:templates/mytemplate.pt')
    config.add_static_view('static', 'myproject:static')
    return config.make_wsgi_app()

    Note that the constructor function accepts a global_config argument, which is a dictionary of key/value pairs mentioned in the [DEFAULT] section of an .ini file. It also accepts a **settings argument, which collects another set of arbitrary key/value pairs. The arbitrary key/value pairs received by this function in **settings will be composed of all the key/value pairs that are present in the [app:MyProject] section (except for the use= setting) when this function is called by the PasteDeploy framework when you run paster serve.

    Our generated development.ini file looks like so:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
    [app:MyProject]
use = egg:MyProject
reload_templates = true
debug_authorization = false
debug_notfound = false
debug_routematch = false
debug_templates = true
default_locale_name = en

[pipeline:main]
pipeline =
    egg:WebError#evalerror
    MyProject

[server:main]
use = egg:Paste#http
host = 0.0.0.0
port = 6543

# Begin logging configuration

[loggers]
keys = root, myproject

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[logger_myproject]
level = DEBUG
handlers =
qualname = myproject

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s

# End logging configuration

    In this case, the myproject.__init__:main function referred to by the entry point URI egg:MyProject (see development.ini for more information about entry point URIs, and how they relate to callables), will receive the key/value pairs {'reload_templates':'true', 'debug_authorization':'false', 'debug_notfound':'false', 'debug_routematch':'false', 'debug_templates':'true', 'default_locale_name':'en'}.

  4. The main function first constructs a Configurator instance, passing a root resource factory (constructor) to it as its root_factory argument, and settings dictionary captured via the **settings kwarg as its settings argument.

    The root resource factory is invoked on every request to retrieve the application’s root resource. It is not called during startup, only when a request is handled.

    The settings dictionary contains all the options in the [app:MyProject] section of our .ini file except the use option (which is internal to Paste) such as reload_templates, debug_authorization, etc.

  5. The main function then calls various methods on the an instance of the class Configurator method. The intent of calling these methods is to populate an application registry, which represents the Pyramid configuration related to the application.

  6. The make_wsgi_app() method is called. The result is a router instance. The router is associated with the application registry implied by the configurator previously populated by other methods run against the Configurator. The router is a WSGI application.

  7. A ApplicationCreated event is emitted (see Using Events for more information about events).

  8. Assuming there were no errors, the main function in myproject returns the router instance created by make_wsgi_app back to PasteDeploy. As far as PasteDeploy is concerned, it is “just another WSGI application”.

  9. PasteDeploy starts the WSGI server defined within the [server:main] section. In our case, this is the Paste#http server (use = egg:Paste#http), and it will listen on all interfaces (host = 0.0.0.0), on port number 6543 (port = 6543). The server code itself is what prints serving on 0.0.0.0:6543 view at http://127.0.0.1:6543. The server serves the application, and the application is running, waiting to receive requests.

Deployment Settings

Note that an augmented version of the values passed as **settings to the Configurator constructor will be available in Pyramid view callable code as request.registry.settings. You can create objects you wish to access later from view code, and put them into the dictionary you pass to the configurator as settings. They will then be present in the request.registry.settings dictionary at application runtime.