This chapter explains what happens between the time you press the "Return" key
on your keyboard after typing pservedevelopment.ini and the time the lines
Servingonhttp://localhost:6543 are output to your console.

The easiest and best-documented way to start and serve a Pyramid
application is to use the pserve 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 pservedevelopment.ini.

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.

pserve passes the development.ini path to plaster which
finds an available configuration loader that recognizes the ini format.

plaster finds the plaster_pastedeploy library which binds
the PasteDeploy library and returns a parser that can understand
the format.

The PasteDeploy 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's paste.app_factoryentry point 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 "composite" (e.g.,
[composite:main]), refer to the documentation for that particular
composite to understand how to make it refer to your Pyramid
application. In most cases, a Pyramid application built from a cookiecutter
will have a single [app:main] section in it, and this will be the
application served.

The framework finds all logging related configuration in the .ini
file and uses it to configure the Python standard library logging system for
this application. See Logging Configuration for more information.

The application's constructor named by the entry point referenced 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
Pyramidrouter 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 an .ini file (if [DEFAULT] 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.

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 {pyramid.reload_templates=true,pyramid.debug_authorization=false,pyramid.debug_notfound=false,pyramid.debug_routematch=false,pyramid.default_locale_name=en,andpyramid.includes=pyramid_debugtoolbar}. See Environment Variables and .ini File Settings
for the meanings of these keys.

The main function first constructs a
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.

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

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.

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

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 on port 6543
for both IPv4 and IPv6 (listen=localhost:6543). The server
code itself is what prints Servingonhttp://localhost:6543. The server
serves the application, and the application is running, waiting to receive requests.

Note that an augmented version of the values passed as **settings to the
Configurator constructor will be available in
Pyramidview 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.