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