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