From e8561f919548e2fe17f82d98e2a13e1e4e85bf40 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 7 Jul 2011 01:57:18 -0500 Subject: Added/updated documentation for the new interactive shell. --- docs/narr/project.rst | 96 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 33 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 631412f42..be673c370 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -258,8 +258,9 @@ develop``, you can use an interactive Python shell to examine your :app:`Pyramid` project's :term:`resource` and :term:`view` objects from a Python prompt. To do so, use your virtualenv's ``paster pshell`` command. -The first argument to ``pshell`` is the path to your application's ``.ini`` -file. The second is the ``app`` section name inside the ``.ini`` file which +The argument to ``pshell`` follows the format ``config_file#section_name`` +where ``config_file`` is the path to your application's ``.ini`` file and +``section_name`` is the ``app`` section name inside the ``.ini`` file which points to *your application* as opposed to any other section within the ``.ini`` file. For example, if your application ``.ini`` file might have a ``[app:MyProject]`` section that looks like so: @@ -280,16 +281,21 @@ name ``MyProject`` as a section name: .. code-block:: text - [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject + [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini#MyProject Python 2.4.5 (#1, Aug 29 2008, 12:27:37) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin - Type "help" for more information. "root" is the Pyramid app root object, - "registry" is the Pyramid registry object. + + Default Variables: + app The WSGI Application + root The root of the default resource tree. + registry The Pyramid registry object. + settings The Pyramid settings object. + >>> root >>> registry - >>> registry.settings['debug_notfound'] + >>> settings['debug_notfound'] False >>> from myproject.views import my_view >>> from pyramid.request import Request @@ -297,31 +303,16 @@ name ``MyProject`` as a section name: >>> my_view(r) {'project': 'myproject'} -Two names are made available to the pshell user as globals: ``root`` and -``registry``. ``root`` is the the object returned by the default :term:`root -factory` in your application. ``registry`` is the :term:`application -registry` object associated with your project's application (often accessed -within view code as ``request.registry``). - -If you have `IPython `_ installed in -the interpreter you use to invoke the ``paster`` command, the ``pshell`` -command will use an IPython interactive shell instead of a standard Python -interpreter shell. If you don't want this to happen, even if you have -IPython installed, you can pass the ``--disable-ipython`` flag to the -``pshell`` command to use a standard Python interpreter shell -unconditionally. - -.. code-block:: text - - [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ - development.ini MyProject +The WSGI application that is loaded will be available in the shell as the +``app`` global. Also, if the application that is loaded is the +:app:`Pyramid` app with no surrounding middleware, the ``root`` object +returned by the default :term:`root factory`, ``registry``, and ``settings`` +will be available. -You should always use a section name argument that refers to the actual -``app`` section within the Paste configuration file that points at your -:app:`Pyramid` application *without any middleware wrapping*. In particular, -a section name is inappropriate as the second argument to ``pshell`` if the -configuration section it names is a ``pipeline`` rather than an ``app``. For -example, if you have the following ``.ini`` file content: +The interactive shell will not be able to load some of the globals like +``root``, ``registry`` and ``settings`` if the section name specified when +loading ``pshell`` is not referencing your :app:`Pyramid` application directly. +For example, if you have the following ``.ini`` file content: .. code-block:: ini :linenos: @@ -341,12 +332,51 @@ example, if you have the following ``.ini`` file content: Use ``MyProject`` instead of ``main`` as the section name argument to ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell -development.ini MyProject``). If you use ``main`` instead, an error will -occur. Use the most specific reference to your application within the -``.ini`` file possible as the section name argument. +development.ini#MyProject``). Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). +Extending the Shell +~~~~~~~~~~~~~~~~~~~ + +It is sometimes convenient when using the interactive shell often to have +some variables significant to your application already loaded as globals +when you start the ``pshell``. To facilitate this, ``pshell`` will look +for a special ``[pshell]`` section in your INI file and expose the subsequent +key/value pairs to the shell. + +For example, you want to expose your model to the shell, along with the +database session so that you can mutate the model on an actual database. +Here, we'll assume your model is stored in the ``myapp.models`` package. + +.. code-block:: ini + :linenos: + + [pshell] + m = myapp.models + session = myapp.models.DBSession + t = transaction + +When this INI file is loaded, the extra variables ``m``, ``session`` and +``t`` will be available for use immediately. This happens regardless of +whether the ``registry`` and other special variables are loaded. + +IPython +~~~~~~~ + +If you have `IPython `_ installed in +the interpreter you use to invoke the ``paster`` command, the ``pshell`` +command will use an IPython interactive shell instead of a standard Python +interpreter shell. If you don't want this to happen, even if you have +IPython installed, you can pass the ``--disable-ipython`` flag to the +``pshell`` command to use a standard Python interpreter shell +unconditionally. + +.. code-block:: text + + [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ + development.ini#MyProject + .. index:: single: running an application single: paster serve -- cgit v1.2.3 From 7565006cf1f3b929d9ea54256214f3a39385936a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 10 Jul 2011 00:30:30 -0400 Subject: add info to changes.txt and whatsnew about pshell changes; removed unused import and unwrap string --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index be673c370..ab7023561 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -336,6 +336,8 @@ development.ini#MyProject``). Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). +.. _extending_pshell: + Extending the Shell ~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From f4a80417c886938dec83071a4d62238c78bf8810 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 12 Jul 2011 00:10:54 -0400 Subject: add docs about logging config --- docs/narr/project.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index ab7023561..4a7f63176 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -12,9 +12,9 @@ A project is a directory that contains at least one Python :term:`package`. You'll use a scaffold to create a project, and you'll create your application logic within a package that lives inside the project. Even if your application is extremely simple, it is useful to place code that drives the -application within a package, because a package is more easily extended with -new code. An application that lives inside a package can also be distributed -more easily than one which does not live within a package. +application within a package, because: 1) a package is more easily extended +with new code and 2) an application that lives inside a package can also be +distributed more easily than one which does not live within a package. :app:`Pyramid` comes with a variety of scaffolds that you can use to generate a project. Each scaffold makes different configuration assumptions about @@ -559,7 +559,8 @@ The generated ``development.ini`` file looks like so: :linenos: This file contains several "sections" including ``[app:MyProject]``, -``[pipeline:main]``, and ``[server:main]``. +``[pipeline:main]``, ``[server:main]`` and several other sections related to +logging configuration. The ``[app:MyProject]`` section represents configuration for your application. This section name represents the ``MyProject`` application (and @@ -643,6 +644,16 @@ for each request. application be nonblocking as all application code will run in its own thread, provided by the server you're using. +The sections that live between the markers ``# Begin logging configuration`` +and ``# End logging configuration`` represent Python's standard library +:mod:`logging` module configuration for your application. The sections +between these two markers are passed to the `logging module's config file +configuration engine +`_ when the +``paster serve`` or ``paster pshell`` commands are executed. The default +configuration sends application logging output to the standard error output +of your terminal. + See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other applications, :term:`middleware` and alternate :term:`WSGI` server -- cgit v1.2.3 From ae4c577d12a16396b45515e81415b2b16f8e93e8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 13 Jul 2011 20:48:38 -0400 Subject: move all paster commands to a separate chapter --- docs/narr/project.rst | 148 ++++---------------------------------------------- 1 file changed, 11 insertions(+), 137 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 4a7f63176..4b08d09f6 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -194,7 +194,8 @@ Elided output from a run of this command is shown below: This will install a :term:`distribution` representing your project into the interpreter's library set so it can be found by ``import`` statements and by -:term:`PasteDeploy` commands such as ``paster serve`` and ``paster pshell``. +:term:`PasteDeploy` commands such as ``paster serve``, ``paster pshell``, +``paster proutes`` and ``paster pviews``. .. index:: single: running tests @@ -243,142 +244,6 @@ The tests themselves are found in the ``tests.py`` module in your ``paster create`` -generated project. Within a project generated by the ``pyramid_starter`` scaffold, a single sample test exists. -.. index:: - single: interactive shell - single: IPython - single: paster pshell - -.. _interactive_shell: - -The Interactive Shell ---------------------- - -Once you've installed your program for development using ``setup.py -develop``, you can use an interactive Python shell to examine your -:app:`Pyramid` project's :term:`resource` and :term:`view` objects from a -Python prompt. To do so, use your virtualenv's ``paster pshell`` command. - -The argument to ``pshell`` follows the format ``config_file#section_name`` -where ``config_file`` is the path to your application's ``.ini`` file and -``section_name`` is the ``app`` section name inside the ``.ini`` file which -points to *your application* as opposed to any other section within the -``.ini`` file. For example, if your application ``.ini`` file might have a -``[app:MyProject]`` section that looks like so: - -.. code-block:: ini - :linenos: - - [app:MyProject] - use = egg:MyProject - reload_templates = true - debug_authorization = false - debug_notfound = false - debug_templates = true - default_locale_name = en - -If so, you can use the following command to invoke a debug shell using the -name ``MyProject`` as a section name: - -.. code-block:: text - - [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini#MyProject - Python 2.4.5 (#1, Aug 29 2008, 12:27:37) - [GCC 4.0.1 (Apple Inc. build 5465)] on darwin - - Default Variables: - app The WSGI Application - root The root of the default resource tree. - registry The Pyramid registry object. - settings The Pyramid settings object. - - >>> root - - >>> registry - - >>> settings['debug_notfound'] - False - >>> from myproject.views import my_view - >>> from pyramid.request import Request - >>> r = Request.blank('/') - >>> my_view(r) - {'project': 'myproject'} - -The WSGI application that is loaded will be available in the shell as the -``app`` global. Also, if the application that is loaded is the -:app:`Pyramid` app with no surrounding middleware, the ``root`` object -returned by the default :term:`root factory`, ``registry``, and ``settings`` -will be available. - -The interactive shell will not be able to load some of the globals like -``root``, ``registry`` and ``settings`` if the section name specified when -loading ``pshell`` is not referencing your :app:`Pyramid` application directly. -For example, if you have the following ``.ini`` file content: - -.. code-block:: ini - :linenos: - - [app:MyProject] - use = egg:MyProject - reload_templates = true - debug_authorization = false - debug_notfound = false - debug_templates = true - default_locale_name = en - - [pipeline:main] - pipeline = - egg:WebError#evalerror - MyProject - -Use ``MyProject`` instead of ``main`` as the section name argument to -``pshell`` against the above ``.ini`` file (e.g. ``paster pshell -development.ini#MyProject``). - -Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). - -.. _extending_pshell: - -Extending the Shell -~~~~~~~~~~~~~~~~~~~ - -It is sometimes convenient when using the interactive shell often to have -some variables significant to your application already loaded as globals -when you start the ``pshell``. To facilitate this, ``pshell`` will look -for a special ``[pshell]`` section in your INI file and expose the subsequent -key/value pairs to the shell. - -For example, you want to expose your model to the shell, along with the -database session so that you can mutate the model on an actual database. -Here, we'll assume your model is stored in the ``myapp.models`` package. - -.. code-block:: ini - :linenos: - - [pshell] - m = myapp.models - session = myapp.models.DBSession - t = transaction - -When this INI file is loaded, the extra variables ``m``, ``session`` and -``t`` will be available for use immediately. This happens regardless of -whether the ``registry`` and other special variables are loaded. - -IPython -~~~~~~~ - -If you have `IPython `_ installed in -the interpreter you use to invoke the ``paster`` command, the ``pshell`` -command will use an IPython interactive shell instead of a standard Python -interpreter shell. If you don't want this to happen, even if you have -IPython installed, you can pass the ``--disable-ipython`` flag to the -``pshell`` command to use a standard Python interpreter shell -unconditionally. - -.. code-block:: text - - [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ - development.ini#MyProject - .. index:: single: running an application single: paster serve @@ -1067,4 +932,13 @@ This pattern can be used to rearrage code referred to by any Pyramid API argument which accepts a :term:`dotted Python name` or direct object reference. +Using the Interactive Shell +--------------------------- + +It is possible to use a Python interpreter prompt loaded with a similar +configuration as would be loaded if you were running your Pyramid application +via ``paster serve``. This can be a useful debugging tool. See +:ref:`interactive_shell` for more details. + + -- cgit v1.2.3 From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/project.rst | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 4b08d09f6..cdf57729d 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -249,7 +249,6 @@ create`` -generated project. Within a project generated by the single: paster serve single: reload single: startup - single: mod_wsgi Running The Project Application ------------------------------- @@ -295,6 +294,10 @@ For more detailed information about the startup process, see configuration file settings that influence startup and runtime behavior, see :ref:`environment_chapter`. +.. index:: + single: mod_wsgi + single: WSGI + Viewing the Application ----------------------- @@ -533,6 +536,9 @@ implementations. to your application's ``main`` function as ``global_config`` (see the reference to the ``main`` function in :ref:`init_py`). +.. index:: + single: production.ini + ``production.ini`` ~~~~~~~~~~~~~~~~~~~ @@ -658,6 +664,9 @@ who want to use your application. setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. +.. index:: + single: setup.cfg + ``setup.cfg`` ~~~~~~~~~~~~~ @@ -753,6 +762,9 @@ also informs Python that the directory which contains it is a *package*. Line 12 returns a :term:`WSGI` application to the caller of the function (Paste). +.. index:: + single: views.py + ``views.py`` ~~~~~~~~~~~~ @@ -823,6 +835,9 @@ about which sort of data storage you'll want to use, so the sample application uses an instance of :class:`myproject.resources.Root` to represent the root. +.. index:: + single: static directory + ``static`` ~~~~~~~~~~ @@ -863,6 +878,9 @@ example. See :ref:`testing_chapter` for more information about writing :app:`Pyramid` unit tests. +.. index:: + pair: modifying; package structure + .. _modifying_package_structure: Modifying Package Structure -- cgit v1.2.3 From 0c2141c78c85898c87495f040617699e79a49c04 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sat, 23 Jul 2011 23:14:36 -0700 Subject: Removed repetitive and badly formed sentence --- docs/narr/project.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index cdf57729d..34a641c4a 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -99,9 +99,8 @@ We'll choose the ``pyramid_starter`` scaffold for this purpose. $ bin/paster create -t pyramid_starter -The above command uses the ``paster`` command to create a project using the -``pyramid_starter`` scaffold. The ``paster create`` command creates project -from a scaffold. To use a different scaffold, such as +The above command uses the ``paster create`` command to create a project with the +``pyramid_starter`` scaffold. To use a different scaffold, such as ``pyramid_routesalchemy``, you'd just change the last argument. For example: .. code-block:: text -- cgit v1.2.3 From 82c2fc57e36c65493ba0fa39368733c189d954c6 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sat, 23 Jul 2011 23:55:31 -0700 Subject: replace extra 'the' with 'be' --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 34a641c4a..bf1a610b4 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -176,7 +176,7 @@ command ``python setup.py develop`` The file named ``setup.py`` will be in the root of the paster-generated project directory. The ``python`` you're invoking should be the one that lives in the ``bin`` directory of your virtual Python environment. Your -terminal's current working directory *must* the the newly created project +terminal's current working directory *must* be the newly created project directory. For example: .. code-block:: text -- cgit v1.2.3 From 5c05ef41bfe538b1ce802bb163a40dbd8880e757 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sun, 24 Jul 2011 00:10:35 -0700 Subject: extra 's' removed --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index bf1a610b4..32846f848 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -467,7 +467,7 @@ the default. The ``use`` setting is the only setting *required* in the ``[app:MyProject]`` section unless you've changed the callable referred to by the ``egg:MyProject`` entry point to accept more arguments: other settings you -add to this section are passed as keywords arguments to the callable +add to this section are passed as keyword arguments to the callable represented by this entry point (``main`` in our ``__init__.py`` module). You can provide startup-time configuration parameters to your application by adding more settings to this section. -- cgit v1.2.3 From 17fd1443f4f8107023c90286e46362dd035d480c Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sun, 24 Jul 2011 00:14:23 -0700 Subject: typo --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 32846f848..ca7d97ca9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -481,7 +481,7 @@ template changes will not require an application restart to be detected. See The ``debug_templates`` setting in the ``[app:MyProject]`` section is a :app:`Pyramid` -specific setting which is passed into the framework. If it exists, and its value is ``true``, :term:`Chameleon` template exceptions will -contained more detailed and helpful information about the error than when +contain more detailed and helpful information about the error than when this value is ``false``. See :ref:`debug_templates_section` for more information. -- cgit v1.2.3 From 04e4f2f03d487d5b8c55b52ea1d882b7464574c0 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sun, 24 Jul 2011 00:18:43 -0700 Subject: Removed extra 'if' --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index ca7d97ca9..47cdbdc83 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -458,7 +458,7 @@ the default. point can thus be referred to as a "Paste application factory in the ``MyProject`` project which has the entry point named ``main`` where the entry point refers to a ``main`` function in the ``mypackage`` module". - If indeed if you open up the ``__init__.py`` module generated within the + Indeed, if you open up the ``__init__.py`` module generated within the ``myproject`` package, you'll see a ``main`` function. This is the function called by :term:`PasteDeploy` when the ``paster serve`` command is invoked against our application. It accepts a global configuration -- cgit v1.2.3 From b210666d36ef855df45478526d3ed54196955a00 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sun, 24 Jul 2011 00:40:34 -0700 Subject: missing word --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 47cdbdc83..5f4878470 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -846,7 +846,7 @@ template. It includes CSS and images. ``templates/mytemplate.pt`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The single :term:`Chameleon` template exists in the project. Its contents +The single :term:`Chameleon` template that exists in the project. Its contents are too long to show here, but it displays a default page when rendered. It is referenced by the call to ``add_view`` as the ``renderer`` attribute in the ``__init__`` file. See :ref:`views_which_use_a_renderer` for more -- cgit v1.2.3 From 875ded31e7fdd0c85d1c91458248581b9dd729d7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 30 Jul 2011 01:50:24 -0600 Subject: Updated all of the docs to reflect the new pyramid.* settings prefix. --- docs/narr/project.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5f4878470..3b1b45eda 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -472,22 +472,22 @@ represented by this entry point (``main`` in our ``__init__.py`` module). You can provide startup-time configuration parameters to your application by adding more settings to this section. -The ``reload_templates`` setting in the ``[app:MyProject]`` section is a -:app:`Pyramid` -specific setting which is passed into the framework. If it +The ``pyramid.reload_templates`` setting in the ``[app:MyProject]`` section is +a :app:`Pyramid` -specific setting which is passed into the framework. If it exists, and its value is ``true``, :term:`Chameleon` and :term:`Mako` template changes will not require an application restart to be detected. See :ref:`reload_templates_section` for more information. -The ``debug_templates`` setting in the ``[app:MyProject]`` section is a +The ``pyramid.debug_templates`` setting in the ``[app:MyProject]`` section is a :app:`Pyramid` -specific setting which is passed into the framework. If it exists, and its value is ``true``, :term:`Chameleon` template exceptions will contain more detailed and helpful information about the error than when this value is ``false``. See :ref:`debug_templates_section` for more information. -.. warning:: The ``reload_templates`` and ``debug_templates`` options should - be turned off for production applications, as template rendering is slowed - when either is turned on. +.. warning:: The ``pyramid.reload_templates`` and ``pyramid.debug_templates`` + options should be turned off for production applications, as template + rendering is slowed when either is turned on. Various other settings may exist in this section having to do with debugging or influencing runtime behavior of a :app:`Pyramid` application. See @@ -795,14 +795,14 @@ file call to ``add_view``). See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``reload_templates = +.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = true`` directive indicating that templates should be reloaded when they change, you won't need to restart the application server to see changes you make to templates. During development, this is handy. If this directive had been ``false`` (or if the directive did not exist), you would need to restart the application server for each template change. For production applications, you should - set your project's ``reload_templates`` to ``false`` to increase + set your project's ``pyramid.reload_templates`` to ``false`` to increase the speed at which templates may be rendered. .. index:: -- cgit v1.2.3 From c6d9f191e920536fdb274d15ef956a5e8151bbc2 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 9 Aug 2011 14:18:32 -0400 Subject: fix project.rst to deal with scaffold changes --- docs/narr/project.rst | 51 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 13 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 3b1b45eda..b4a0e1d45 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -99,18 +99,18 @@ We'll choose the ``pyramid_starter`` scaffold for this purpose. $ bin/paster create -t pyramid_starter -The above command uses the ``paster create`` command to create a project with the -``pyramid_starter`` scaffold. To use a different scaffold, such as +The above command uses the ``paster create`` command to create a project with +the ``pyramid_starter`` scaffold. To use a different scaffold, such as ``pyramid_routesalchemy``, you'd just change the last argument. For example: .. code-block:: text $ bin/paster create -t pyramid_routesalchemy -``paster create`` will ask you a single question: the *name* of the -project. You should use a string without spaces and with only letters -in it. Here's sample output from a run of ``paster create`` for a -project we name ``MyProject``: +``paster create`` will ask you a single question: the *name* of the project. +You should use a string without spaces and with only letters in it. Here's +sample output from a run of ``paster create`` for a project we name +``MyProject``: .. code-block:: text @@ -309,6 +309,23 @@ browser like what is displayed in the following image: This is the page shown by default when you visit an unmodified ``paster create`` -generated ``pyramid_starter`` application in a browser. +If you click on the image shown at the right hand top of the page ("^DT"), +you'll be presented with a debug toolbar that provides various niceties while +you're developing. This image will float above every HTML page served by +:app:`Pyramid` while you develop an application, and allows you show the +toolbar as necessary. Click on ``Hide`` to hide the toolbar and show the +image again. + +.. image:: project-debug.png + +For more information about what the debug toolbar allows you to do, see `the +documentation for pyramid_debugtoolbar +`_. + +The debug toolbar will not be shown (and all debugging will be turned off) +when you use the ``production.ini`` file instead of the ``development.ini`` +ini file to run the application. + .. sidebar:: Using an Alternate WSGI Server The code generated by a :app:`Pyramid` scaffold assumes that you @@ -419,8 +436,6 @@ serve``, as well as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: -.. latexbroken? - .. literalinclude:: MyProject/development.ini :language: ini :linenos: @@ -489,6 +504,14 @@ information. options should be turned off for production applications, as template rendering is slowed when either is turned on. +The ``pyramid.include`` setting in the ``[app:MyProject]`` section tells +Pyramid to "include" configuration from another package. In this case, the +line ``pyramid.include = pyramid_debugtoolbar`` tells Pyramid to include +configuration from the ``pyramid_debugtoolbar`` package. This turns on a +debugging panel in development mode which will be shown on the right hand +side of the screen. Including the debug toolbar will also make it possible +to interactively debug exceptions when an error occurs. + Various other settings may exist in this section having to do with debugging or influencing runtime behavior of a :app:`Pyramid` application. See :ref:`environment_chapter` for more information about these settings. @@ -543,11 +566,13 @@ implementations. The ``production.ini`` file is a :term:`PasteDeploy` configuration file with a purpose much like that of ``development.ini``. However, it disables the -WebError interactive debugger, replacing it with a logger which outputs -exception messages to ``stderr`` by default. It also turns off template -development options such that templates are not automatically reloaded when -changed, and turns off all debugging options. You can use this file instead -of ``development.ini`` when you put your application into production. +debug toolbar, replacing it with a logger which outputs exception messages to +``stderr`` by default. It also turns off template development options such +that templates are not automatically reloaded when changed, and turns off all +debugging options. It allows you to configure a ``weberror#error_catcher`` +section that will cause exceptions to be sent to an email address when they +are uncaught. You can use this file instead of ``development.ini`` when you +put your application into production. .. index:: single: MANIFEST.in -- cgit v1.2.3 From 06247f77d3a7f6757c6082badb00154b6f626922 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 9 Aug 2011 14:21:55 -0400 Subject: instructions about how to turn the toolbar off --- docs/narr/project.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4a0e1d45..baf4c86fa 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -326,6 +326,28 @@ The debug toolbar will not be shown (and all debugging will be turned off) when you use the ``production.ini`` file instead of the ``development.ini`` ini file to run the application. +You can also turn the debug toolbar off by editing ``development.ini`` and +commenting out the line ``pyramid.include = pyramid_debugtoolbar``. For +example, instead of: + +.. code-block:: ini + :linenos: + + [app:MyApp] + ... + pyramid.include = pyramid_debugtoolbar + +Put a hash mark in front of the ``pyramid.include`` line: + +.. code-block:: ini + :linenos: + + [app:MyApp] + ... + #pyramid.include = pyramid_debugtoolbar + +Then restart the application to see that the toolbar has been turned off. + .. sidebar:: Using an Alternate WSGI Server The code generated by a :app:`Pyramid` scaffold assumes that you -- cgit v1.2.3