From b1b92284f496800a4dfd2cea72cb9be07ba8661c Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 16:52:14 -0400 Subject: First cut at import of quick tutorial. --- docs/quick_tutorial/ini.rst | 144 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/quick_tutorial/ini.rst (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst new file mode 100644 index 000000000..85b07812e --- /dev/null +++ b/docs/quick_tutorial/ini.rst @@ -0,0 +1,144 @@ +================================================= +03: Application Configuration with ``.ini`` Files +================================================= + +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 ` 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. + +Objectives +========== + +- Modify our ``setup.py`` to have an entry point telling Pyramid the + location of the WSGI app + +- Create an application driven by a ``.ini`` file + +- Startup the application with Pyramid's ``pserve`` command + +- Move code into the package's ``__init__.py`` + +Steps +===== + +#. First we copy the results of the previous step: + + .. code-block:: bash + + (env27)$ cd ..; cp -r package ini; cd ini + +#. Our ``ini/setup.py`` needs a setuptools "entry point" in the + ``setup()`` function: + + .. literalinclude:: ini/setup.py + :linenos: + +#. We can now install our project, thus generating (or re-generating) an + "egg" at ``ini/tutorial.egg-info``: + + .. code-block:: bash + + (env27)$ python setup.py develop + +#. Let's make a file ``ini/development.ini`` for our configuration: + + .. 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``: + + .. literalinclude:: ini/tutorial/__init__.py + :linenos: + +#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: + + .. code-block:: bash + + (env27)$ rm tutorial/app.py + +#. Run your Pyramid application with: + + .. code-block:: bash + + (env27)$ pserve development.ini --reload + +#. 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 +:ref:`application startup `: + +- ``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 ``tutorial`` package's ``__init__`` has a ``main`` function + +- This function is invoked, with the values from certain ``.ini`` + sections passed in + +The ``.ini`` file is also used for two other functions: + +- *Choice of WSGI server*. ``[server:main]`` wires up the choice of WSGI + *server* for your WSGI *application*. In this case, we are using + ``wsgiref`` bundled in the Python library. + +- *Python logging*. Pyramid uses Python standard logging, which needs a + number of configuration values. The ``.ini`` serves this function. + This provides the console log output that you see on startup and each + request. + +- *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port + 6543. + +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``. + +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 +============ + +#. 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? + +#. The entry point in ``setup.py`` didn't mention ``__init__.py`` when + it the ``main`` function. Why not? + +.. seealso:: + :ref:`pyramid:project_narr`, + :ref:`pyramid:scaffolding_chapter`, + :ref:`pyramid:what_is_this_pserve_thing`, + :ref:`pyramid:environment_chapter`, + :ref:`pyramid:paste_chapter` + +Extra Credit +============ + +#. What is the purpose of ``**settings``? What does the ``**`` signify? -- cgit v1.2.3 From 4042c772c8043ac96a22db439a736fec9ea2aafa Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:09:35 -0400 Subject: All the references re-wired. --- docs/quick_tutorial/ini.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 85b07812e..66247c92d 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -9,7 +9,7 @@ Background ========== Pyramid has a first-class concept of -:ref:`configuration ` distinct from code. +:ref:`configuration ` 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 @@ -82,7 +82,7 @@ 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 -:ref:`application startup `: +:ref:`application startup `: - ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial`` @@ -132,11 +132,11 @@ Extra Credit it the ``main`` function. Why not? .. seealso:: - :ref:`pyramid:project_narr`, - :ref:`pyramid:scaffolding_chapter`, - :ref:`pyramid:what_is_this_pserve_thing`, - :ref:`pyramid:environment_chapter`, - :ref:`pyramid:paste_chapter` + :ref:`project_narr`, + :ref:`scaffolding_chapter`, + :ref:`what_is_this_pserve_thing`, + :ref:`environment_chapter`, + :ref:`paste_chapter` Extra Credit ============ -- cgit v1.2.3 From 0a784868bdbc3a0eb226ed00e8d89cda9d181ec5 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:11:42 -0400 Subject: Fix naming of virtualenv prefix. --- docs/quick_tutorial/ini.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 66247c92d..4210e8608 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -35,7 +35,7 @@ Steps .. code-block:: bash - (env27)$ cd ..; cp -r package ini; cd ini + (env)$ cd ..; cp -r package ini; cd ini #. Our ``ini/setup.py`` needs a setuptools "entry point" in the ``setup()`` function: @@ -48,7 +48,7 @@ Steps .. code-block:: bash - (env27)$ python setup.py develop + (env)$ python setup.py develop #. Let's make a file ``ini/development.ini`` for our configuration: @@ -66,13 +66,13 @@ Steps .. code-block:: bash - (env27)$ rm tutorial/app.py + (env)$ rm tutorial/app.py #. Run your Pyramid application with: .. code-block:: bash - (env27)$ pserve development.ini --reload + (env)$ pserve development.ini --reload #. Open ``http://localhost:6543/``. -- cgit v1.2.3 From b0b28ede912c817a62a84b97c332e39eda02d166 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:14:53 +0200 Subject: s/env/venv just for sake of consistency --- docs/quick_tutorial/ini.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 4210e8608..eb43b00ed 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -35,7 +35,7 @@ Steps .. code-block:: bash - (env)$ cd ..; cp -r package ini; cd ini + (venv)$ cd ..; cp -r package ini; cd ini #. Our ``ini/setup.py`` needs a setuptools "entry point" in the ``setup()`` function: @@ -48,7 +48,7 @@ Steps .. code-block:: bash - (env)$ python setup.py develop + (venv)$ python setup.py develop #. Let's make a file ``ini/development.ini`` for our configuration: @@ -66,13 +66,13 @@ Steps .. code-block:: bash - (env)$ rm tutorial/app.py + (venv)$ rm tutorial/app.py #. Run your Pyramid application with: .. code-block:: bash - (env)$ pserve development.ini --reload + (venv)$ pserve development.ini --reload #. Open ``http://localhost:6543/``. -- cgit v1.2.3 From d749bf4c987c4ab90bd5f89326e7d4059e4f47b3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:18:11 +0200 Subject: make example links clickable, for convenience --- docs/quick_tutorial/ini.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index eb43b00ed..f732d3653 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -74,7 +74,7 @@ Steps (venv)$ pserve development.ini --reload -#. Open ``http://localhost:6543/``. +#. Open http://localhost:6543/. Analysis ======== -- cgit v1.2.3 From 187104fd81418beeb51592913041d9751bafe08d Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 09:27:43 -0400 Subject: Quick Tutorial: Improve the setup instructions (adapted from Steve Piercy's work), particularly for Windows. Change all the steps to use $VENV/bin prefixes on commands (don't presume that they have done source env/bin/activate). --- docs/quick_tutorial/ini.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index f732d3653..35d6b46cc 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -35,7 +35,7 @@ Steps .. code-block:: bash - (venv)$ 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: @@ -48,7 +48,7 @@ Steps .. code-block:: bash - (venv)$ python setup.py develop + $ $VENV/bin/python setup.py develop #. Let's make a file ``ini/development.ini`` for our configuration: @@ -66,13 +66,13 @@ Steps .. code-block:: bash - (venv)$ rm tutorial/app.py + $ rm tutorial/app.py #. Run your Pyramid application with: .. code-block:: bash - (venv)$ pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload #. Open http://localhost:6543/. -- cgit v1.2.3 From b731b5fca253d9d95b3307490aa585e194676c01 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Thu, 26 Sep 2013 17:41:44 -0400 Subject: Quick Tour: shorten the setup part and point to Quick Tutorial Requirements for more explanation. Cross link each Quick Tour section with its Quick Tutorial match. --- docs/quick_tutorial/ini.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/quick_tutorial/ini.rst') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 35d6b46cc..630b1faa5 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -1,3 +1,5 @@ +.. _qtut_ini: + ================================================= 03: Application Configuration with ``.ini`` Files ================================================= -- cgit v1.2.3