| commit | author | age | ||
| b731b5 | 1 | .. _qtut_ini: |
| PE | 2 | |
| b1b922 | 3 | ================================================= |
| PE | 4 | 03: Application Configuration with ``.ini`` Files |
| 5 | ================================================= | |
| 6 | ||
| 7 | Use Pyramid's ``pserve`` command with a ``.ini`` configuration file for | |
| 8 | simpler, better application running. | |
| 9 | ||
| 8e6520 | 10 | |
| b1b922 | 11 | Background |
| PE | 12 | ========== |
| 13 | ||
| 50b8b4 | 14 | Pyramid has a first-class concept of :ref:`configuration <configuration_narr>` distinct from code. |
| SP | 15 | This approach is optional, but its presence makes it distinct from other Python web frameworks. |
| 315e46 | 16 | It taps into Python's :term:`Setuptools` library, which establishes conventions for installing and providing ":term:`entry point`\ s" for Python projects. |
| 50b8b4 | 17 | Pyramid uses an :term:`entry point` to let a Pyramid application know where to find the WSGI app. |
| 8e6520 | 18 | |
| b1b922 | 19 | |
| PE | 20 | Objectives |
| 21 | ========== | |
| 22 | ||
| 50b8b4 | 23 | - Modify our ``setup.py`` to have an :term:`entry point` telling Pyramid the location of the WSGI app. |
| b1b922 | 24 | |
| 8e6520 | 25 | - Create an application driven by an ``.ini`` file. |
| b1b922 | 26 | |
| 8e6520 | 27 | - Start the application with Pyramid's ``pserve`` command. |
| b1b922 | 28 | |
| 8e6520 | 29 | - Move code into the package's ``__init__.py``. |
| SP | 30 | |
| b1b922 | 31 | |
| PE | 32 | Steps |
| 33 | ===== | |
| 34 | ||
| a1bc90 | 35 | #. First we copy the results of the previous step: |
| b1b922 | 36 | |
| a1bc90 | 37 | .. code-block:: bash |
| b1b922 | 38 | |
| a1bc90 | 39 | cd ..; cp -r package ini; cd ini |
| b1b922 | 40 | |
| a1bc90 | 41 | #. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function: |
| b1b922 | 42 | |
| a1bc90 | 43 | .. literalinclude:: ini/setup.py |
| SP | 44 | :linenos: |
| 45 | :emphasize-lines: 13-17 | |
| b1b922 | 46 | |
| a1bc90 | 47 | #. We can now install our project, thus generating (or re-generating) an "egg" at ``ini/tutorial.egg-info``: |
| b1b922 | 48 | |
| a1bc90 | 49 | .. code-block:: bash |
| b1b922 | 50 | |
| a1bc90 | 51 | $VENV/bin/pip install -e . |
| b1b922 | 52 | |
| a1bc90 | 53 | #. Let's make a file ``ini/development.ini`` for our configuration: |
| b1b922 | 54 | |
| a1bc90 | 55 | .. literalinclude:: ini/development.ini |
| SP | 56 | :language: ini |
| 57 | :linenos: | |
| b1b922 | 58 | |
| a1bc90 | 59 | #. We can refactor our startup code from the previous step's ``app.py`` into ``ini/tutorial/__init__.py``: |
| b1b922 | 60 | |
| a1bc90 | 61 | .. literalinclude:: ini/tutorial/__init__.py |
| SP | 62 | :linenos: |
| b1b922 | 63 | |
| a1bc90 | 64 | #. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: |
| b1b922 | 65 | |
| a1bc90 | 66 | .. code-block:: bash |
| b1b922 | 67 | |
| a1bc90 | 68 | rm tutorial/app.py |
| b1b922 | 69 | |
| a1bc90 | 70 | #. Run your Pyramid application with: |
| b1b922 | 71 | |
| a1bc90 | 72 | .. code-block:: bash |
| b1b922 | 73 | |
| a1bc90 | 74 | $VENV/bin/pserve development.ini --reload |
| b1b922 | 75 | |
| a1bc90 | 76 | #. Open http://localhost:6543/. |
| b1b922 | 77 | |
| PE | 78 | Analysis |
| 79 | ======== | |
| 80 | ||
| 8e6520 | 81 | Our ``development.ini`` file is read by ``pserve`` and serves to bootstrap our |
| SP | 82 | application. Processing then proceeds as described in the Pyramid chapter on |
| 4042c7 | 83 | :ref:`application startup <startup_chapter>`: |
| b1b922 | 84 | |
| 8e6520 | 85 | - ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial``. |
| b1b922 | 86 | |
| 50b8b4 | 87 | - The projects's ``setup.py`` has defined an :term:`entry point` (lines 10-13) for the project's "main" :term:`entry point` of ``tutorial:main``. |
| b1b922 | 88 | |
| 8e6520 | 89 | - The ``tutorial`` package's ``__init__`` has a ``main`` function. |
| b1b922 | 90 | |
| 8e6520 | 91 | - This function is invoked, with the values from certain ``.ini`` sections |
| SP | 92 | passed in. |
| b1b922 | 93 | |
| PE | 94 | The ``.ini`` file is also used for two other functions: |
| 95 | ||
| bcf79f | 96 | - *Configuring the WSGI server*. ``[server:main]`` wires up the choice |
| CS | 97 | of which WSGI *server* for your WSGI *application*. In this case, we |
| 2a84a4 | 98 | are using ``waitress`` which we specified in |
| SP | 99 | ``tutorial/setup.py`` and was installed in the :doc:`requirements` step at the start of this tutorial. It also wires up the *port number*: |
| 30bf73 | 100 | ``listen = localhost:6543`` tells ``waitress`` to listen on host |
| CS | 101 | ``localhost`` at port ``6543``. |
| b1b922 | 102 | |
| 2a84a4 | 103 | .. note:: Running the command ``$VENV/bin/pip install -e .`` will check for previously installed packages in our virtual environment that are specified in our package's ``setup.py`` file, then install our package in editable mode, installing any requirements that were not previously installed. If a requirement was manually installed previously on the command line or otherwise, in this case Waitress, then ``$VENV/bin/pip install -e .`` will merely check that it is installed and move on. |
| SP | 104 | |
| 3c6ea2 | 105 | - *Configuring Python logging*. Pyramid uses Python standard logging, which |
| TS | 106 | needs a number of configuration values. The ``.ini`` serves this function. |
| b1b922 | 107 | This provides the console log output that you see on startup and each |
| PE | 108 | request. |
| 109 | ||
| 110 | We moved our startup code from ``app.py`` to the package's | |
| 8e6520 | 111 | ``tutorial/__init__.py``. This isn't necessary, but it is a common style in |
| SP | 112 | Pyramid to take the WSGI app bootstrapping out of your module's code and put it |
| 113 | in the package's ``__init__.py``. | |
| b1b922 | 114 | |
| 8e6520 | 115 | The ``pserve`` application runner has a number of command-line arguments and |
| SP | 116 | options. We are using ``--reload`` which tells ``pserve`` to watch the |
| 117 | filesystem for changes to relevant code (Python files, the INI file, etc.) and, | |
| 118 | when something changes, restart the application. Very handy during development. | |
| 119 | ||
| b1b922 | 120 | |
| 65687f | 121 | Extra credit |
| b1b922 | 122 | ============ |
| PE | 123 | |
| 8e6520 | 124 | #. If you don't like configuration and/or ``.ini`` files, could you do this |
| SP | 125 | yourself in Python code? |
| b1b922 | 126 | |
| 8e6520 | 127 | #. Can we have multiple ``.ini`` configuration files for a project? Why might |
| SP | 128 | you want to do that? |
| b1b922 | 129 | |
| 50b8b4 | 130 | #. The :term:`entry point` in ``setup.py`` didn't mention ``__init__.py`` when it declared ``tutorial:main`` function. Why not? |
| b1b922 | 131 | |
| 24c406 | 132 | #. What is the purpose of ``**settings``? What does the ``**`` signify? |
| SP | 133 | |
| b1b922 | 134 | .. seealso:: |
| 4042c7 | 135 | :ref:`project_narr`, |
| b52d1a | 136 | :ref:`cookiecutters`, |
| 4042c7 | 137 | :ref:`what_is_this_pserve_thing`, |
| PE | 138 | :ref:`environment_chapter`, |
| 139 | :ref:`paste_chapter` | |
