commit | author | age
|
c6e58b
|
1 |
.. _startup_chapter: |
CM |
2 |
|
|
3 |
Startup |
|
4 |
======= |
|
5 |
|
d9fccb
|
6 |
When you cause a :app:`Pyramid` application to start up in a console window, |
fe96f4
|
7 |
you'll see something much like this show up on the console: |
CM |
8 |
|
bf8014
|
9 |
.. code-block:: bash |
c6e58b
|
10 |
|
bf8014
|
11 |
$ $VENV/bin/pserve development.ini |
SP |
12 |
Starting server in PID 16305. |
|
13 |
serving on http://127.0.0.1:6543 |
c6e58b
|
14 |
|
911882
|
15 |
This chapter explains what happens between the time you press the "Return" key |
SP |
16 |
on your keyboard after typing ``pserve development.ini`` and the time the line |
bf8014
|
17 |
``serving on http://127.0.0.1:6543`` is output to your console. |
c6e58b
|
18 |
|
8c56ae
|
19 |
.. index:: |
CM |
20 |
single: startup process |
4a63f6
|
21 |
pair: settings; .ini |
8c56ae
|
22 |
|
c6e58b
|
23 |
The Startup Process |
CM |
24 |
------------------- |
|
25 |
|
d9fccb
|
26 |
The easiest and best-documented way to start and serve a :app:`Pyramid` |
d3ce2b
|
27 |
application is to use the ``pserve`` command against a :term:`PasteDeploy` |
CM |
28 |
``.ini`` file. This uses the ``.ini`` file to infer settings and starts a |
911882
|
29 |
server listening on a port. For the purposes of this discussion, we'll assume |
SP |
30 |
that you are using this command to run your :app:`Pyramid` application. |
c6e58b
|
31 |
|
d9fccb
|
32 |
Here's a high-level time-ordered overview of what happens when you press |
cfb2b5
|
33 |
``return`` after running ``pserve development.ini``. |
c6e58b
|
34 |
|
cfb2b5
|
35 |
#. The ``pserve`` command is invoked under your shell with the argument |
CM |
36 |
``development.ini``. As a result, Pyramid recognizes that it is meant to |
|
37 |
begin to run and serve an application using the information contained |
|
38 |
within the ``development.ini`` file. |
c6e58b
|
39 |
|
cfb2b5
|
40 |
#. The framework finds a section named either ``[app:main]``, |
d9fccb
|
41 |
``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This |
911882
|
42 |
section represents the configuration of a :term:`WSGI` application that will |
SP |
43 |
be served. If you're using a simple application (e.g., ``[app:main]``), the |
|
44 |
application's ``paste.app_factory`` :term:`entry point` will be named on the |
|
45 |
``use=`` line within the section's configuration. If instead of a simple |
|
46 |
application, you're using a WSGI :term:`pipeline` (e.g., a |
|
47 |
``[pipeline:main]`` section), the application named on the "last" element |
|
48 |
will refer to your :app:`Pyramid` application. If instead of a simple |
|
49 |
application or a pipeline, you're using a "composite" (e.g., |
|
50 |
``[composite:main]``), refer to the documentation for that particular |
|
51 |
composite to understand how to make it refer to your :app:`Pyramid` |
|
52 |
application. In most cases, a Pyramid application built from a scaffold |
|
53 |
will have a single ``[app:main]`` section in it, and this will be the |
|
54 |
application served. |
c6e58b
|
55 |
|
911882
|
56 |
#. The framework finds all :mod:`logging` related configuration in the ``.ini`` |
SP |
57 |
file and uses it to configure the Python standard library logging system for |
|
58 |
this application. See :ref:`logging_config` for more information. |
46ad10
|
59 |
|
02503c
|
60 |
#. The application's *constructor* named by the entry point referenced on the |
911882
|
61 |
``use=`` line of the section representing your :app:`Pyramid` application is |
SP |
62 |
passed the key/value parameters mentioned within the section in which it's |
|
63 |
defined. The constructor is meant to return a :term:`router` instance, |
|
64 |
which is a :term:`WSGI` application. |
c6e58b
|
65 |
|
fd5ae9
|
66 |
For :app:`Pyramid` applications, the constructor will be a function named |
d9fccb
|
67 |
``main`` in the ``__init__.py`` file within the :term:`package` in which |
9f0269
|
68 |
your application lives. If this function succeeds, it will return a |
fd5ae9
|
69 |
:app:`Pyramid` :term:`router` instance. Here's the contents of an example |
9f0269
|
70 |
``__init__.py`` module: |
c6e58b
|
71 |
|
9f0269
|
72 |
.. literalinclude:: MyProject/myproject/__init__.py |
23bfce
|
73 |
:language: python |
c6e58b
|
74 |
:linenos: |
CM |
75 |
|
d9fccb
|
76 |
Note that the constructor function accepts a ``global_config`` argument, |
CM |
77 |
which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]`` |
02503c
|
78 |
section of an ``.ini`` file (if :ref:`[DEFAULT] |
SP |
79 |
<defaults_section_of_pastedeploy_file>` is present). It also accepts a |
911882
|
80 |
``**settings`` argument, which collects another set of arbitrary key/value |
SP |
81 |
pairs. The arbitrary key/value pairs received by this function in |
|
82 |
``**settings`` will be composed of all the key/value pairs that are present |
|
83 |
in the ``[app:main]`` section (except for the ``use=`` setting) when this |
|
84 |
function is called when you run ``pserve``. |
c6e58b
|
85 |
|
9f0269
|
86 |
Our generated ``development.ini`` file looks like so: |
c6e58b
|
87 |
|
9f0269
|
88 |
.. literalinclude:: MyProject/development.ini |
edf394
|
89 |
:language: ini |
c6e58b
|
90 |
:linenos: |
CM |
91 |
|
d9fccb
|
92 |
In this case, the ``myproject.__init__:main`` function referred to by the |
CM |
93 |
entry point URI ``egg:MyProject`` (see :ref:`MyProject_ini` for more |
911882
|
94 |
information about entry point URIs, and how they relate to callables) will |
bf8014
|
95 |
receive the key/value pairs ``{pyramid.reload_templates = true, |
SP |
96 |
pyramid.debug_authorization = false, pyramid.debug_notfound = false, |
|
97 |
pyramid.debug_routematch = false, pyramid.default_locale_name = en, and |
|
98 |
pyramid.includes = pyramid_debugtoolbar}``. See :ref:`environment_chapter` |
|
99 |
for the meanings of these keys. |
c6e58b
|
100 |
|
d9fccb
|
101 |
#. The ``main`` function first constructs a |
6269a1
|
102 |
:class:`~pyramid.config.Configurator` instance, passing the ``settings`` |
MP |
103 |
dictionary captured via the ``**settings`` kwarg as its ``settings`` |
|
104 |
argument. |
d9fccb
|
105 |
|
3d338e
|
106 |
The ``settings`` dictionary contains all the options in the ``[app:main]`` |
CM |
107 |
section of our .ini file except the ``use`` option (which is internal to |
cfb2b5
|
108 |
PasteDeploy) such as ``pyramid.reload_templates``, |
875ded
|
109 |
``pyramid.debug_authorization``, etc. |
d9fccb
|
110 |
|
4396c6
|
111 |
#. The ``main`` function then calls various methods on the instance of the |
CDLG |
112 |
class :class:`~pyramid.config.Configurator` created in the previous step. |
911882
|
113 |
The intent of calling these methods is to populate an :term:`application |
SP |
114 |
registry`, which represents the :app:`Pyramid` configuration related to the |
|
115 |
application. |
c442e4
|
116 |
|
911882
|
117 |
#. The :meth:`~pyramid.config.Configurator.make_wsgi_app` method is called. The |
SP |
118 |
result is a :term:`router` instance. The router is associated with the |
|
119 |
:term:`application registry` implied by the configurator previously |
d9fccb
|
120 |
populated by other methods run against the Configurator. The router is a |
CM |
121 |
WSGI application. |
c6e58b
|
122 |
|
b5655e
|
123 |
#. An :class:`~pyramid.events.ApplicationCreated` event is emitted (see |
6067de
|
124 |
:ref:`events_chapter` for more information about events). |
c6e58b
|
125 |
|
d9fccb
|
126 |
#. Assuming there were no errors, the ``main`` function in ``myproject`` |
3d338e
|
127 |
returns the router instance created by |
cfb2b5
|
128 |
:meth:`pyramid.config.Configurator.make_wsgi_app` back to ``pserve``. As |
CM |
129 |
far as ``pserve`` is concerned, it is "just another WSGI application". |
c6e58b
|
130 |
|
cfb2b5
|
131 |
#. ``pserve`` starts the WSGI *server* defined within the ``[server:main]`` |
030d10
|
132 |
section. In our case, this is the Waitress server (``use = |
07e802
|
133 |
egg:waitress#main``), and it will listen on all interfaces (``listen = |
M |
134 |
127.0.0.1:6543``), on port number 6543. The server code itself |
bf8014
|
135 |
is what prints ``serving on http://127.0.0.1:6543``. The server serves the |
SP |
136 |
application, and the application is running, waiting to receive requests. |
c6e58b
|
137 |
|
ad76ef
|
138 |
.. seealso:: |
02503c
|
139 |
Logging configuration is described in the :ref:`logging_chapter` chapter. |
911882
|
140 |
There, in :ref:`request_logging_with_pastes_translogger`, you will also find |
SP |
141 |
an example of how to configure :term:`middleware` to add pre-packaged |
|
142 |
functionality to your application. |
ad76ef
|
143 |
|
6ce1e0
|
144 |
.. index:: |
CM |
145 |
pair: settings; deployment |
|
146 |
single: custom settings |
|
147 |
|
a1365e
|
148 |
.. _deployment_settings: |
c6e58b
|
149 |
|
a1365e
|
150 |
Deployment Settings |
CM |
151 |
------------------- |
|
152 |
|
|
153 |
Note that an augmented version of the values passed as ``**settings`` to the |
70acd2
|
154 |
:class:`~pyramid.config.Configurator` constructor will be available in |
911882
|
155 |
:app:`Pyramid` :term:`view callable` code as ``request.registry.settings``. You |
SP |
156 |
can create objects you wish to access later from view code, and put them into |
|
157 |
the dictionary you pass to the configurator as ``settings``. They will then be |
|
158 |
present in the ``request.registry.settings`` dictionary at application runtime. |