diff options
Diffstat (limited to 'docs/quick_tutorial/ini.rst')
| -rw-r--r-- | docs/quick_tutorial/ini.rst | 139 |
1 files changed, 67 insertions, 72 deletions
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 3402c50e8..0bb7da1ba 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -7,101 +7,100 @@ Use Pyramid's ``pserve`` command with a ``.ini`` configuration file for simpler, better application running. + Background ========== -Pyramid has a first-class concept of -:ref:`configuration <configuration_narr>` distinct from code. -This approach is optional, but its presence makes it distinct from -other Python web frameworks. It taps into Python's ``setuptools`` -library, which establishes conventions for how Python projects can be -installed and provide "entry points". Pyramid uses an entry point to -let a Pyramid application it where to find the WSGI app. +Pyramid has a first-class concept of :ref:`configuration <configuration_narr>` distinct from code. +This approach is optional, but its presence makes it distinct from other Python web frameworks. +It taps into Python's :term:`Setuptools` library, which establishes conventions for installing and providing ":term:`entry point`\ s" for Python projects. +Pyramid uses an :term:`entry point` to let a Pyramid application know where to find the WSGI app. + Objectives ========== -- Modify our ``setup.py`` to have an entry point telling Pyramid the - location of the WSGI app +- Modify our ``setup.py`` to have an :term:`entry point` telling Pyramid the location of the WSGI app. + +- Create an application driven by an ``.ini`` file. -- Create an application driven by a ``.ini`` file +- Start the application with Pyramid's ``pserve`` command. -- Startup the application with Pyramid's ``pserve`` command +- Move code into the package's ``__init__.py``. -- Move code into the package's ``__init__.py`` Steps ===== -#. First we copy the results of the previous step: +#. First we copy the results of the previous step: - .. code-block:: bash + .. code-block:: bash - $ cd ..; cp -r package ini; cd ini + cd ..; cp -r package ini; cd ini -#. Our ``ini/setup.py`` needs a setuptools "entry point" in the - ``setup()`` function: +#. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function: - .. literalinclude:: ini/setup.py - :linenos: + .. literalinclude:: ini/setup.py + :linenos: + :emphasize-lines: 13-17 -#. We can now install our project, thus generating (or re-generating) an - "egg" at ``ini/tutorial.egg-info``: +#. We can now install our project, thus generating (or re-generating) an "egg" at ``ini/tutorial.egg-info``: - .. code-block:: bash + .. code-block:: bash - $ $VENV/bin/python setup.py develop + $VENV/bin/pip install -e . -#. Let's make a file ``ini/development.ini`` for our configuration: +#. Let's make a file ``ini/development.ini`` for our configuration: - .. literalinclude:: ini/development.ini - :language: ini - :linenos: + .. literalinclude:: ini/development.ini + :language: ini + :linenos: -#. We can refactor our startup code from the previous step's ``app.py`` - into ``ini/tutorial/__init__.py``: +#. We can refactor our startup code from the previous step's ``app.py`` into ``ini/tutorial/__init__.py``: - .. literalinclude:: ini/tutorial/__init__.py - :linenos: + .. literalinclude:: ini/tutorial/__init__.py + :linenos: -#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: +#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: - .. code-block:: bash + .. code-block:: bash - $ rm tutorial/app.py + rm tutorial/app.py -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $ $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/. +#. Open http://localhost:6543/. Analysis ======== -Our ``development.ini`` file is read by ``pserve`` and serves to -bootstrap our application. Processing then proceeds as described in -the Pyramid chapter on +Our ``development.ini`` file is read by ``pserve`` and serves to bootstrap our +application. Processing then proceeds as described in the Pyramid chapter on :ref:`application startup <startup_chapter>`: -- ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial`` +- ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial``. -- The projects's ``setup.py`` has defined an "entry point" (lines 9-10) - for the project "main" entry point of ``tutorial:main`` +- 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``. -- The ``tutorial`` package's ``__init__`` has a ``main`` function +- The ``tutorial`` package's ``__init__`` has a ``main`` function. -- This function is invoked, with the values from certain ``.ini`` - sections passed in +- This function is invoked, with the values from certain ``.ini`` sections + passed in. The ``.ini`` file is also used for two other functions: -- *Configuring the WSGI server*. ``[server:main]`` wires up the choice of - which WSGI *server* for your WSGI *application*. In this case, we are using - ``wsgiref`` bundled in the Python library. It also wires up the *port - number*: ``port = 6543`` tells ``wsgiref`` to listen on port 6543. +- *Configuring the WSGI server*. ``[server:main]`` wires up the choice + of which WSGI *server* for your WSGI *application*. In this case, we + are using ``waitress`` which we specified in + ``tutorial/setup.py`` and was installed in the :doc:`requirements` step at the start of this tutorial. It also wires up the *port number*: + ``listen = localhost:6543`` tells ``waitress`` to listen on host + ``localhost`` at port ``6543``. + + .. 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. - *Configuring Python logging*. Pyramid uses Python standard logging, which needs a number of configuration values. The ``.ini`` serves this function. @@ -109,36 +108,32 @@ The ``.ini`` file is also used for two other functions: request. We moved our startup code from ``app.py`` to the package's -``tutorial/__init__.py``. This isn't necessary, -but it is a common style in Pyramid to take the WSGI app bootstrapping -out of your module's code and put it in the package's ``__init__.py``. +``tutorial/__init__.py``. This isn't necessary, but it is a common style in +Pyramid to take the WSGI app bootstrapping out of your module's code and put it +in the package's ``__init__.py``. + +The ``pserve`` application runner has a number of command-line arguments and +options. We are using ``--reload`` which tells ``pserve`` to watch the +filesystem for changes to relevant code (Python files, the INI file, etc.) and, +when something changes, restart the application. Very handy during development. -The ``pserve`` application runner has a number of command-line arguments -and options. We are using ``--reload`` which tells ``pserve`` to watch -the filesystem for changes to relevant code (Python files, the INI file, -etc.) and, when something changes, restart the application. Very handy -during development. -Extra Credit +Extra credit ============ -#. If you don't like configuration and/or ``.ini`` files, - could you do this yourself in Python code? +#. If you don't like configuration and/or ``.ini`` files, could you do this + yourself in Python code? -#. Can we have multiple ``.ini`` configuration files for a project? Why - might you want to do that? +#. Can we have multiple ``.ini`` configuration files for a project? Why might + you want to do that? -#. The entry point in ``setup.py`` didn't mention ``__init__.py`` when - it declared ``tutorial:main`` function. Why not? +#. The :term:`entry point` in ``setup.py`` didn't mention ``__init__.py`` when it declared ``tutorial:main`` function. Why not? + +#. What is the purpose of ``**settings``? What does the ``**`` signify? .. seealso:: :ref:`project_narr`, - :ref:`scaffolding_chapter`, + :ref:`cookiecutters`, :ref:`what_is_this_pserve_thing`, :ref:`environment_chapter`, :ref:`paste_chapter` - -Extra Credit -============ - -#. What is the purpose of ``**settings``? What does the ``**`` signify? |