Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
159 lines (127 sloc) 7.45 KB


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

$ $VENV/bin/pserve development.ini
Starting server in PID 16305.
serving on

This chapter explains what happens between the time you press the "Return" key on your keyboard after typing pserve development.ini and the time the line serving on is output to your console.

The Startup Process

The easiest and best-documented way to start and serve a :app:`Pyramid` application is to use the pserve command against a :term:`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 :app:`Pyramid` application.

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

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

  2. The framework finds a section named either [app:main], [pipeline:main], or [composite:main] in the .ini file. This section represents the configuration of a :term:`WSGI` application that will be served. If you're using a simple application (e.g., [app:main]), the application's paste.app_factory :term:`entry point` will be named on the use= line within the section's configuration. If instead of a simple application, you're using a WSGI :term:`pipeline` (e.g., a [pipeline:main] section), the application named on the "last" element will refer to your :app:`Pyramid` application. If instead of a simple application or a pipeline, you're using a "composite" (e.g., [composite:main]), refer to the documentation for that particular composite to understand how to make it refer to your :app:`Pyramid` application. In most cases, a Pyramid application built from a scaffold will have a single [app:main] section in it, and this will be the application served.

  3. The framework finds all :mod:`logging` related configuration in the .ini file and uses it to configure the Python standard library logging system for this application. See :ref:`logging_config` for more information.

  4. The application's constructor named by the entry point referenced on the use= line of the section representing your :app:`Pyramid` application is passed the key/value parameters mentioned within the section in which it's defined. The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application.

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

    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 (if :ref:`[DEFAULT] <defaults_section_of_pastedeploy_file>` is present). 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:main] section (except for the use= setting) when this function is called when you run pserve.

    Our generated development.ini file looks like so:

    In this case, the myproject.__init__:main function referred to by the entry point URI egg:MyProject (see :ref:`MyProject_ini` for more information about entry point URIs, and how they relate to callables) will receive the key/value pairs {pyramid.reload_templates = true, pyramid.debug_authorization = false, pyramid.debug_notfound = false, pyramid.debug_routematch = false, pyramid.default_locale_name = en, and pyramid.includes = pyramid_debugtoolbar}. See :ref:`environment_chapter` for the meanings of these keys.

  5. The main function first constructs a :class:`~pyramid.config.Configurator` instance, passing the settings dictionary captured via the **settings kwarg as its settings argument.

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

  6. The main function then calls various methods on the instance of the class :class:`~pyramid.config.Configurator` created in the previous step. The intent of calling these methods is to populate an :term:`application registry`, which represents the :app:`Pyramid` configuration related to the application.

  7. The :meth:`~pyramid.config.Configurator.make_wsgi_app` method is called. The result is a :term:`router` instance. The router is associated with the :term:`application registry` implied by the configurator previously populated by other methods run against the Configurator. The router is a WSGI application.

  8. An :class:`` event is emitted (see :ref:`events_chapter` for more information about events).

  9. Assuming there were no errors, the main function in myproject returns the router instance created by :meth:`pyramid.config.Configurator.make_wsgi_app` back to pserve. As far as pserve is concerned, it is "just another WSGI application".

  10. pserve starts the WSGI server defined within the [server:main] section. In our case, this is the Waitress server (use = egg:waitress#main), and it will listen on all interfaces (host =, on port number 6543 (port = 6543). The server code itself is what prints serving on 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 :class:`~pyramid.config.Configurator` constructor will be available in :app:`Pyramid` :term:`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.

Something went wrong with that request. Please try again.