Skip to content
This repository
tag: 1.0a1
Fetching contributors…

Cannot retrieve contributors at this time

file 145 lines (114 sloc) 6.625 kb

Startup

When you cause :mod:`pyramid` 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 :mod:`pyramid` application is to use the paster serve 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 :mod:`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 :term:`PasteDeploy` paster command is invoked under your shell with the arguments serve and development.ini. As a result, the :term:`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 :term:`WSGI` application that will be served. If you're using a simple application (e.g. an [app:main] section of a default-generated :mod:`pyramid` project), the application :term:`entry point` or :term:`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 :term:`pipeline` (e.g. a [pipeline:main] section), the application named on the "last" element will refer to your :mod:`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 :mod:`pyramid` application.

  3. The application's constructor (named by the entry point reference or dotted Python name on the use= line) 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 :mod:`pyramid` applications, the constructor will be a function named app in the __init__.py file within the :term:`package` in which your application lives. If this function succeeds, it will return a :mod:`pyramid` :term:`router` instance. Here's the contents of an example __init__.py 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 the configuration 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:main] section (except for the use= setting) when this function is called by the :term:`PasteDeploy` framework when you run paster serve.

    Our generated development.ini file looks like so:

    In this case, the myproject.run:app function referred to by the entry point URI egg:MyProject#app (see :ref:`MyProject_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_templates':'true', 'default_locale_name':'en'}.

  4. The app function first constructs a :class:`pyramid.configuration.Configurator` instance, passing get_root to it as its root_factory argument, and settings dictionary captured via the **settings kwarg as its settings argument.

    get_root is a root factory callable that is invoked on every request to retrieve the application root. It is not called during startup, only when a request is handled.

    The settings dictionary contains all the options in the [app:main] section of our .ini file except the "use" option (which is internal to paste). In this case, **settings will be something like {'reload_templates':'true', 'debug_authorization':'false', 'debug_notfound':'false', 'debug_templates':'true', 'default_locale_name':'en'}.

  5. The app function then calls various methods on the an instance of the class :class:`pyramid.configuration.Configurator` method. The intent of calling these methods is to populate an :term:`application registry`, which represents the :mod:`pyramid` configuration related to the application.

  6. The :meth:`pyramid.configuration.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.

  7. A :class:`pyramid.interfaces.IApplicationCreated` event is emitted (see :ref:`events_chapter` for more information about events).

  8. Assuming there were no errors, the app 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.

Something went wrong with that request. Please try again.