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/commandline.rst | 288 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 docs/narr/commandline.rst (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst new file mode 100644 index 000000000..0c591f6d1 --- /dev/null +++ b/docs/narr/commandline.rst @@ -0,0 +1,288 @@ +.. _command_line_chapter: + +Command-Line Pyramid +==================== + +Your :app:`Pyramid` application can be controlled and inspected using a +variety of command-line utilities. These utilities are documented in this +chapter. + +.. index:: + pair: matching views; printing + single: paster pviews + +.. _displaying_matching_views: + +Displaying Matching Views for a Given URL +----------------------------------------- + +For a big application with several views, it can be hard to keep the view +configuration details in your head, even if you defined all the views +yourself. You can use the ``paster pviews`` command in a terminal window to +print a summary of matching routes and views for a given URL in your +application. The ``paster pviews`` command accepts two arguments. The +first argument to ``pviews`` is the path to your application's ``.ini`` file +and section name inside the ``.ini`` file which points to your application. +This should be of the format ``config_file#section_name``. The second argument +is the URL to test for matching views. + +Here is an example for a simple view configuration using :term:`traversal`: + +.. code-block:: text + :linenos: + + $ ../bin/paster pviews development.ini tutorial /FrontPage + + URL = /FrontPage + + context: + view name: + + View: + ----- + tutorial.views.view_page + required permission = view + +The output always has the requested URL at the top and below that all the +views that matched with their view configuration details. In this example +only one view matches, so there is just a single *View* section. For each +matching view, the full code path to the associated view callable is shown, +along with any permissions and predicates that are part of that view +configuration. + +A more complex configuration might generate something like this: + +.. code-block:: text + :linenos: + + $ ../bin/paster pviews development.ini#shootout /about + + URL = /about + + context: + view name: about + + Route: + ------ + route name: about + route pattern: /about + route path: /about + subpath: + route predicates (request method = GET) + + View: + ----- + shootout.views.about_view + required permission = view + view predicates (request_param testing, header X/header) + + Route: + ------ + route name: about_post + route pattern: /about + route path: /about + subpath: + route predicates (request method = POST) + + View: + ----- + shootout.views.about_view_post + required permission = view + view predicates (request_param test) + + View: + ----- + shootout.views.about_view_post2 + required permission = view + view predicates (request_param test2) + +In this case, we are dealing with a :term:`URL dispatch` application. This +specific URL has two matching routes. The matching route information is +displayed first, followed by any views that are associated with that route. +As you can see from the second matching route output, a route can be +associated with more than one view. + +For a URL that doesn't match any views, ``paster pviews`` will simply print +out a *Not found* message. + + +.. index:: + single: interactive shell + single: IPython + single: paster pshell + single: 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 execute expressions in +a Python environment exactly like the one that will be used when your +application runs "for real". To do so, use the ``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:: + pair: routes; printing + single: paster proutes + single: proutes + +.. _displaying_application_routes: + +Displaying All Application Routes +--------------------------------- + +You can use the ``paster proutes`` command in a terminal window to print a +summary of routes related to your application. Much like the ``paster +pshell`` command (see :ref:`interactive_shell`), the ``paster proutes`` +command accepts one argument with the format ``config_file#section_name``. +The ``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. + +For example: + +.. code-block:: text + :linenos: + + [chrism@thinko MyProject]$ ../bin/paster proutes development.ini#MyProject + Name Pattern View + ---- ------- ---- + home / + home2 / + another /another None + static/ static/*subpath + catchall /*subpath + +``paster proutes`` generates a table. The table has three columns: a Name +name column, a Pattern column, and a View column. The items listed in the +Name column are route names, the items listen in the Pattern column are route +patterns, and the items listed in the View column are representations of the +view callable that will be invoked when a request matches the associated +route pattern. The view column may show ``None`` if no associated view +callable could be found. If no routes are configured within your +application, nothing will be printed to the console when ``paster proutes`` +is executed. + -- cgit v1.2.3 From 9343b6f9f2e243f878ccf8d126ff9cc4bd5878ee Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Thu, 14 Jul 2011 09:18:44 -0700 Subject: eliminated repeated word --- docs/narr/commandline.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 0c591f6d1..5fad9e227 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -277,7 +277,7 @@ For example: catchall /*subpath ``paster proutes`` generates a table. The table has three columns: a Name -name column, a Pattern column, and a View column. The items listed in the +column, a Pattern column, and a View column. The items listed in the Name column are route names, the items listen in the Pattern column are route patterns, and the items listed in the View column are representations of the view callable that will be invoked when a request matches the associated -- cgit v1.2.3 From f7afa751d7ca36a97474099c30923eeeade33b03 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Thu, 14 Jul 2011 09:19:51 -0700 Subject: corrected typo --- docs/narr/commandline.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 5fad9e227..68078ab70 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -278,7 +278,7 @@ For example: ``paster proutes`` generates a table. The table has three columns: a Name column, a Pattern column, and a View column. The items listed in the -Name column are route names, the items listen in the Pattern column are route +Name column are route names, the items listed in the Pattern column are route patterns, and the items listed in the View column are representations of the view callable that will be invoked when a request matches the associated route pattern. The view column may show ``None`` if no associated view -- cgit v1.2.3 From 5fb458c0dd70096e5d619e42992390bb1af071e1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 16 Jul 2011 01:08:43 -0400 Subject: - Added a section entitled "Writing a Script" to the "Command-Line Pyramid" chapter. --- docs/narr/commandline.rst | 151 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 68078ab70..fccf095d3 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -286,3 +286,154 @@ callable could be found. If no routes are configured within your application, nothing will be printed to the console when ``paster proutes`` is executed. +.. _writing_a_script: + +Writing a Script +---------------- + +All web applications are, at their hearts, systems which accept a request and +return a response. When a request is accepted by a :app:`Pyramid` +application, the system receives state from the request which is later relied +on your application code. For example, one :term:`view callable` may assume +it's working against a request that has a ``request.matchdict`` of a +particular composition, while another assumes a different composition of the +matchdict. + +In the meantime, it's convenient to be able to write a Python script that can +work "in a Pyramid environment", for instance to update database tables used +by your :app:`Pyramid` application. But a "real" Pyramid environment doesn't +have a completely static state independent of a request; your application +(and Pyramid itself) is almost always reliant on being able to obtain +information from a request. When you run a Python script that simply imports +code from your application and tries to run it, there just is no request +data, because there isn't any real web request. Therefore some parts of your +application and some Pyramid APIs will not work. + +For this reason, :app:`Pyramid` makes it possible to run a script in an +environment much like the environment produced when a particular +:term:`request` reaches your :app:`Pyramid` application. This is achieved by +using the :func:`pyramid.paster.bootstrap` command in the body of your +script. + +In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a +single argument, which accepts the :term:`PasteDeploy` ``.ini`` file +representing Pyramid your application configuration as a single argument: + +.. code-block:: python + + from pyramid.paster import bootstrap + info = bootstrap('/path/to/my/development.ini') + print info['request'].route_url('home') + +:func:`pyramid.paster.bootstrap` returns a dictionary containing +framework-related information. This dictionary will always contain a +:term:`request` object as its ``request`` key. + +The following keys are also available in the ``info`` dictionary returned by +:func:`~pyramid.paster.bootstrap`: + +request + + A :class:`pyramid.request.Request` object implying the current request + state for your script. + +app + + The :term:`WSGI` application object generated by bootstrapping. + +root + + The :term:`resource` root of your :app:`Pyramid` application. This is an + object generated by the :term:`root factory` configured in your + application. + +registry + + The :term:`application registry` of your :app:`Pyramid` application. + +closer + + A parameterless callable that can be used to pop an internal + :app:`Pyramid` threadlocal stack (used by + :func:`pyramid.threadlocal.get_current_registry` and + :func:`pyramid.threadlocal.get_current_request`) when your scripting job + is finished. + +Let's assume that the ``/path/to/my/development.ini`` file used in the +example above looks like so: + +.. code-block:: ini + + [pipeline:main] + pipeline = egg:WebError#evalerror + another + + [app:another] + use = egg:MyProject + +The configuration loaded by the above bootstrap example will use the +configuration implied by the ``[pipeline:main]`` section of your +configuration file by default. Specifying ``/path/to/my/development.ini`` is +logically equivalent to specifying ``/path/to/my/development.ini#main``. In +this case, we'll be using a configuration that includes an ``app`` object +which is wrapped in the WebError ``evalerror`` middleware. + +You can also specify a particular *section* of the PasteDeploy ``.ini`` file +to load. By default, Pyramid assumes the section name you want to load is +``main``: + +.. code-block:: python + + from pyramid.paster import bootstrap + info = bootstrap('/path/to/my/development.ini#another') + print info['request'].route_url('home') + +The above example specifies the ``another`` ``app``, ``pipeline``, or +``composite`` section of your PasteDeploy configuration file. In the case +that we're using a configuration file that looks like this: + +.. code-block:: ini + + [pipeline:main] + pipeline = egg:WebError#evalerror + another + + [app:another] + use = egg:MyProject + +It will mean that the ``/path/to/my/development.ini#another`` argument passed +to bootstrap will imply the ``[app:another]`` section in our configuration +file. Therefore, it will not wrap the WSGI application present in the info +dictionary as ``app`` using WebError's ``evalerror`` middleware. The ``app`` +object present in the info dictionary returned by +:func:`~pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` +instead. + +By default, Pyramid will general a suitable request object in the ``info`` +dictionary anchored at the root path (``/``). You can alternately supply +your own :class:`pyramid.request.Request` instance to the +:func:`~pyramid.paster.bootstrap` function, to set up request parameters +beforehand: + +.. code-block:: python + + from pyramid.request import Request + request = Request.blank('/another/url') + from pyramid.paster import bootstrap + info = bootstrap('/path/to/my/development.ini#another', request=request) + print info['request'].path_info # will print '/another/url' + +When your scripting logic finishes, it's good manners (but not required) to +call the ``closer`` callback: + +.. code-block:: python + + from pyramid.paster import bootstrap + info = bootstrap('/path/to/my/development.ini') + + # .. do stuff ... + + info['closer']() + + + -- cgit v1.2.3 From 12382c2b61660f65d7f2dc852102e346ad0d46ed Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 16 Jul 2011 01:18:01 -0400 Subject: note version reqt; fix dangling ref --- docs/narr/commandline.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index fccf095d3..6691ea70a 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -315,6 +315,8 @@ environment much like the environment produced when a particular using the :func:`pyramid.paster.bootstrap` command in the body of your script. +.. note:: This feature is new as of :app:`Pyramid` 1.1. + In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a single argument, which accepts the :term:`PasteDeploy` ``.ini`` file representing Pyramid your application configuration as a single argument: @@ -329,7 +331,7 @@ representing Pyramid your application configuration as a single argument: framework-related information. This dictionary will always contain a :term:`request` object as its ``request`` key. -The following keys are also available in the ``info`` dictionary returned by +The following keys are available in the ``info`` dictionary returned by :func:`~pyramid.paster.bootstrap`: request @@ -379,8 +381,7 @@ this case, we'll be using a configuration that includes an ``app`` object which is wrapped in the WebError ``evalerror`` middleware. You can also specify a particular *section* of the PasteDeploy ``.ini`` file -to load. By default, Pyramid assumes the section name you want to load is -``main``: +to load instead of ``main``: .. code-block:: python @@ -409,9 +410,9 @@ object present in the info dictionary returned by :func:`~pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` instead. -By default, Pyramid will general a suitable request object in the ``info`` -dictionary anchored at the root path (``/``). You can alternately supply -your own :class:`pyramid.request.Request` instance to the +By default, Pyramid will general a request object in the ``info`` dictionary +anchored at the root path (``/``). You can alternately supply your own +:class:`pyramid.request.Request` instance to the :func:`~pyramid.paster.bootstrap` function, to set up request parameters beforehand: -- cgit v1.2.3 From 8a8724de56c8dcce763fdb5630c77cb69a149572 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 16 Jul 2011 01:29:52 -0400 Subject: promote bootstrap to major feature --- docs/narr/commandline.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 6691ea70a..b2a921eef 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -437,4 +437,3 @@ call the ``closer`` callback: info['closer']() - -- cgit v1.2.3 From 795aec4ba786c4920be60f9ac80e650816ea044f Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sat, 16 Jul 2011 09:39:04 -0700 Subject: typo in func name --- docs/narr/commandline.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index b2a921eef..98b06c1ba 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -332,7 +332,7 @@ framework-related information. This dictionary will always contain a :term:`request` object as its ``request`` key. The following keys are available in the ``info`` dictionary returned by -:func:`~pyramid.paster.bootstrap`: +:func:`pyramid.paster.bootstrap`: request -- cgit v1.2.3 From fcece8fe59e2ba17d54209a296edb70bd0f63b29 Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sat, 16 Jul 2011 09:58:19 -0700 Subject: Mmm, maybe the bad func name was pasted from an emacs buffer --- docs/narr/commandline.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 98b06c1ba..bc210904f 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -407,13 +407,13 @@ to bootstrap will imply the ``[app:another]`` section in our configuration file. Therefore, it will not wrap the WSGI application present in the info dictionary as ``app`` using WebError's ``evalerror`` middleware. The ``app`` object present in the info dictionary returned by -:func:`~pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` +:func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` instead. By default, Pyramid will general a request object in the ``info`` dictionary anchored at the root path (``/``). You can alternately supply your own :class:`pyramid.request.Request` instance to the -:func:`~pyramid.paster.bootstrap` function, to set up request parameters +:func:`pyramid.paster.bootstrap` function, to set up request parameters beforehand: .. code-block:: python -- cgit v1.2.3 From 42eaadb95ae2bfabc364ffbfa2769ad131d943be Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 16 Jul 2011 14:05:44 -0500 Subject: garden --- docs/narr/commandline.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index bc210904f..9adb04d4b 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -294,7 +294,7 @@ Writing a Script All web applications are, at their hearts, systems which accept a request and return a response. When a request is accepted by a :app:`Pyramid` application, the system receives state from the request which is later relied -on your application code. For example, one :term:`view callable` may assume +on by your application code. For example, one :term:`view callable` may assume it's working against a request that has a ``request.matchdict`` of a particular composition, while another assumes a different composition of the matchdict. @@ -410,7 +410,7 @@ object present in the info dictionary returned by :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` instead. -By default, Pyramid will general a request object in the ``info`` dictionary +By default, Pyramid will generate a request object in the ``info`` dictionary anchored at the root path (``/``). You can alternately supply your own :class:`pyramid.request.Request` instance to the :func:`pyramid.paster.bootstrap` function, to set up request parameters -- cgit v1.2.3 From 795ddb42a12777f12fc5605fa908106a8d65cffd Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 16 Jul 2011 14:05:53 -0500 Subject: Renamed the 'info' dict to 'env' in scripting. --- docs/narr/commandline.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 9adb04d4b..c43145b4c 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -324,14 +324,14 @@ representing Pyramid your application configuration as a single argument: .. code-block:: python from pyramid.paster import bootstrap - info = bootstrap('/path/to/my/development.ini') - print info['request'].route_url('home') + env = bootstrap('/path/to/my/development.ini') + print env['request'].route_url('home') :func:`pyramid.paster.bootstrap` returns a dictionary containing framework-related information. This dictionary will always contain a :term:`request` object as its ``request`` key. -The following keys are available in the ``info`` dictionary returned by +The following keys are available in the ``env`` dictionary returned by :func:`pyramid.paster.bootstrap`: request @@ -386,8 +386,8 @@ to load instead of ``main``: .. code-block:: python from pyramid.paster import bootstrap - info = bootstrap('/path/to/my/development.ini#another') - print info['request'].route_url('home') + env = bootstrap('/path/to/my/development.ini#another') + print env['request'].route_url('home') The above example specifies the ``another`` ``app``, ``pipeline``, or ``composite`` section of your PasteDeploy configuration file. In the case @@ -404,13 +404,13 @@ that we're using a configuration file that looks like this: It will mean that the ``/path/to/my/development.ini#another`` argument passed to bootstrap will imply the ``[app:another]`` section in our configuration -file. Therefore, it will not wrap the WSGI application present in the info +file. Therefore, it will not wrap the WSGI application present in the ``env`` dictionary as ``app`` using WebError's ``evalerror`` middleware. The ``app`` -object present in the info dictionary returned by +object present in the ``env`` dictionary returned by :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` instead. -By default, Pyramid will generate a request object in the ``info`` dictionary +By default, Pyramid will generate a request object in the ``env`` dictionary anchored at the root path (``/``). You can alternately supply your own :class:`pyramid.request.Request` instance to the :func:`pyramid.paster.bootstrap` function, to set up request parameters @@ -421,8 +421,8 @@ beforehand: from pyramid.request import Request request = Request.blank('/another/url') from pyramid.paster import bootstrap - info = bootstrap('/path/to/my/development.ini#another', request=request) - print info['request'].path_info # will print '/another/url' + env = bootstrap('/path/to/my/development.ini#another', request=request) + print env['request'].path_info # will print '/another/url' When your scripting logic finishes, it's good manners (but not required) to call the ``closer`` callback: @@ -430,10 +430,10 @@ call the ``closer`` callback: .. code-block:: python from pyramid.paster import bootstrap - info = bootstrap('/path/to/my/development.ini') + env = bootstrap('/path/to/my/development.ini') # .. do stuff ... - info['closer']() + env['closer']() -- cgit v1.2.3 From 69452f63ab2efa39c9273646959341287ba5ee15 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 16 Jul 2011 18:26:12 -0500 Subject: Changed the URL generation example to be more practical. --- docs/narr/commandline.rst | 60 +++++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 25 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index c43145b4c..30e678f07 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -390,39 +390,50 @@ to load instead of ``main``: print env['request'].route_url('home') The above example specifies the ``another`` ``app``, ``pipeline``, or -``composite`` section of your PasteDeploy configuration file. In the case -that we're using a configuration file that looks like this: +``composite`` section of your PasteDeploy configuration file. The ``app`` +object present in the ``env`` dictionary returned by +:func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`. -.. code-block:: ini +Changing the Request +~~~~~~~~~~~~~~~~~~~~ - [pipeline:main] - pipeline = egg:WebError#evalerror - another +By default, Pyramid will generate a request object in the ``env`` dictionary +for the URL ``http://localhost:80/``. This means that any URLs generated +by Pyramid during the execution of your script will be anchored here. This +is generally not what you want. - [app:another] - use = egg:MyProject +So how do we make Pyramid generate the correct URLs? -It will mean that the ``/path/to/my/development.ini#another`` argument passed -to bootstrap will imply the ``[app:another]`` section in our configuration -file. Therefore, it will not wrap the WSGI application present in the ``env`` -dictionary as ``app`` using WebError's ``evalerror`` middleware. The ``app`` -object present in the ``env`` dictionary returned by -:func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router` -instead. +Assuming that you have a route configured in your application like so: -By default, Pyramid will generate a request object in the ``env`` dictionary -anchored at the root path (``/``). You can alternately supply your own -:class:`pyramid.request.Request` instance to the -:func:`pyramid.paster.bootstrap` function, to set up request parameters -beforehand: +.. code-block:: python + + config.add_route('verify', '/verify/{code}') + +You need to inform the Pyramid environment that the WSGI application is +handling requests from a certain base. For example, we want to mount our +application at `example.com/prefix` and the generated URLs should use HTTPS. +This can be done by mutating the request object: .. code-block:: python - from pyramid.request import Request - request = Request.blank('/another/url') from pyramid.paster import bootstrap - env = bootstrap('/path/to/my/development.ini#another', request=request) - print env['request'].path_info # will print '/another/url' + env = bootstrap('/path/to/my/development.ini#another') + env['request'].host = 'example.com' + env['request'].scheme = 'https' + env['request'].script_name = '/prefix' + print env['request'].application_url + # will print 'https://example.com/prefix/another/url' + +Now you can readily use Pyramid's APIs for generating URLs: + +.. code-block:: python + + route_url('verify', env['request'], code='1337') + # will return 'https://example.com/prefix/verify/1337' + +Cleanup +~~~~~~~ When your scripting logic finishes, it's good manners (but not required) to call the ``closer`` callback: @@ -436,4 +447,3 @@ call the ``closer`` callback: env['closer']() - -- cgit v1.2.3 From 7141f0dfc4b77817017a530cfd2dbb62b4836332 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 16 Jul 2011 20:25:49 -0400 Subject: mention manual logging config --- docs/narr/commandline.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 30e678f07..890f42c42 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -447,3 +447,15 @@ call the ``closer`` callback: env['closer']() +Setting Up Logging +~~~~~~~~~~~~~~~~~~ + +By default, :func:`pyramid.paster.bootstrap` does not configure logging +parameters present in the configuration file. If you'd like to configure +logging based on ``[logger]`` and related sections in the configuration file, +use the following command: + +.. code-block:: python + + import logging + logging.fileConfig('/path/to/my/development.ini') -- cgit v1.2.3 From af056046970db9b1d3732f4c5978fcb3fb863d1f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 16 Jul 2011 21:23:07 -0400 Subject: - Change paster pviews and paster proutes to use bootstrap. --- docs/narr/commandline.rst | 125 ++++++++++++++++++++++++---------------------- 1 file changed, 64 insertions(+), 61 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 890f42c42..b52faed20 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -20,18 +20,19 @@ For a big application with several views, it can be hard to keep the view configuration details in your head, even if you defined all the views yourself. You can use the ``paster pviews`` command in a terminal window to print a summary of matching routes and views for a given URL in your -application. The ``paster pviews`` command accepts two arguments. The -first argument to ``pviews`` is the path to your application's ``.ini`` file -and section name inside the ``.ini`` file which points to your application. -This should be of the format ``config_file#section_name``. The second argument -is the URL to test for matching views. +application. The ``paster pviews`` command accepts two arguments. The first +argument to ``pviews`` is the path to your application's ``.ini`` file and +section name inside the ``.ini`` file which points to your application. This +should be of the format ``config_file#section_name``. The second argument is +the URL to test for matching views. The ``section_name`` may be omitted; if +it is, it's considered to be ``main``. Here is an example for a simple view configuration using :term:`traversal`: .. code-block:: text :linenos: - $ ../bin/paster pviews development.ini tutorial /FrontPage + $ ../bin/paster pviews development.ini#tutorial /FrontPage URL = /FrontPage @@ -125,9 +126,8 @@ application runs "for real". To do so, use the ``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: +points to your application. For example, if your application ``.ini`` file +might have a ``[app:MyProject]`` section that looks like so: .. code-block:: ini :linenos: @@ -145,58 +145,41 @@ 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'} + chrism@thinko env26]$ bin/paster pshell starter/development.ini#MyProject + Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) + [GCC 4.4.3] on linux2 + Type "help" for more information. + + Environment: + app The WSGI application. + registry Active Pyramid registry. + request Active request object. + root Root of the default resource tree. + root_factory Default root factory used to create `root`. + >>> root + + >>> registry + + >>> 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. +``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 ``request`` 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: +You can also simply rely on the ``main`` default section name by omitting any +hash after the filename: -.. 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 +.. code-block:: text -Use ``MyProject`` instead of ``main`` as the section name argument to -``pshell`` against the above ``.ini`` file (e.g. ``paster pshell -development.ini#MyProject``). + chrism@thinko env26]$ bin/paster pshell starter/development.ini Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). @@ -224,8 +207,27 @@ Here, we'll assume your model is stored in the ``myapp.models`` package. 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. +``t`` will be available for use immediately. For example: + +.. code-block:: text + + chrism@thinko env26]$ bin/paster pshell starter/development.ini + Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) + [GCC 4.4.3] on linux2 + Type "help" for more information. + + Environment: + app The WSGI application. + registry Active Pyramid registry. + request Active request object. + root Root of the default resource tree. + root_factory Default root factory used to create `root`. + + Custom Variables: + m myapp.models + session myapp.models.DBSession + t transaction + >>> IPython ~~~~~~~ @@ -258,9 +260,10 @@ You can use the ``paster proutes`` command in a terminal window to print a summary of routes related to your application. Much like the ``paster pshell`` command (see :ref:`interactive_shell`), the ``paster proutes`` command accepts one argument with the format ``config_file#section_name``. -The ``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. +The ``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. By default, the ``section_name`` is ``main`` and +can be omitted. For example: -- 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/commandline.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index b52faed20..a6ba99e17 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -183,6 +183,9 @@ hash after the filename: Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). +.. index:: + pair: pshell; extending + .. _extending_pshell: Extending the Shell @@ -229,6 +232,9 @@ When this INI file is loaded, the extra variables ``m``, ``session`` and t transaction >>> +.. index:: + single: IPython + IPython ~~~~~~~ @@ -289,6 +295,10 @@ callable could be found. If no routes are configured within your application, nothing will be printed to the console when ``paster proutes`` is executed. +.. index:: + single: scripting + single: bootstrap + .. _writing_a_script: Writing a Script -- cgit v1.2.3 From 5adf4c099905cb41f68b38d6443bd2fe62c76889 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 19:03:26 -0400 Subject: add description of keys and values --- docs/narr/commandline.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index a6ba99e17..f4cf951ba 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -192,10 +192,11 @@ 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. +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. Each key is a variable name that will be +global within the pshell session; each value is a :term:`dotted Python name`. 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. -- 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/commandline.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index f4cf951ba..509af7dd3 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -134,11 +134,11 @@ might have a ``[app:MyProject]`` section that looks like so: [app:MyProject] use = egg:MyProject - reload_templates = true - debug_authorization = false - debug_notfound = false - debug_templates = true - default_locale_name = en + pyramid.reload_templates = true + pyramid.debug_authorization = false + pyramid.debug_notfound = false + pyramid.debug_templates = true + pyramid.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: @@ -160,7 +160,7 @@ name ``MyProject`` as a section name: >>> registry - >>> registry.settings['debug_notfound'] + >>> registry.settings['pyramid.debug_notfound'] False >>> from myproject.views import my_view >>> from pyramid.request import Request -- cgit v1.2.3 From 1311321d454ded6226b09f929ebc9e4aa2c12771 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 6 Aug 2011 18:58:26 -0400 Subject: add tweens module, add docs for ptweens and tweens to hooks --- docs/narr/commandline.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 73 insertions(+), 2 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 509af7dd3..6f969196f 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -297,8 +297,79 @@ application, nothing will be printed to the console when ``paster proutes`` is executed. .. index:: - single: scripting - single: bootstrap + pair: tweens; printing + single: paster ptweens + single: ptweens + +.. _displaying_tweens: + +Displaying "Tweens" +------------------- + +A user can get a representation of both the implicit :term:`tween` ordering +(the ordering specified by calls to +:meth:`pyramid.config.Configurator.add_tween`) and the explicit tween +ordering (specified by the ``pyramid.tweens`` configuration setting) +orderings using the ``paster ptweens`` command. Handler factories which are +functions or classes will show up as a standard Python dotted name in the +``paster ptweens`` output. Tween factories which are *instances* will show +their module and class name; the Python object id of the instance will be +appended. + +For example, here's the ``paster pwteens`` command run against a system +configured without any explicit tweens: + +.. code-block:: text + :linenos: + + [chrism@thinko starter]$ ../bin/paster ptweens development.ini + "pyramid.tweens" config value NOT set (implicitly ordered tweens used) + + Position Name + -------- ---- + 0 pyramid.router.excview_tween_factory + +Here's the ``paster pwteens`` command run against a system configured *with* +explicit tweens defined in its ``development.ini`` file: + +.. code-block:: text + :linenos: + + [chrism@thinko starter]$ ../bin/paster ptweens development.ini + "pyramid.tweens" config value set (explicitly ordered tweens used) + + Explicit Tween Chain (used) + + Position Name + -------- ---- + 0 pyramid.tweens.excview_tween_factory + 1 starter.tween_factory1 + 2 starter.tween_factory2 + + Implicit Tween Chain (not used) + + Position Name + -------- ---- + 0 pyramid.tweens.excview_tween_factory + +Here's the application configuration section of the ``development.ini`` used +by the above ``paster ptweens`` command which reprorts that the explicit +tween chain is used: + +.. code-block:: text + :linenos: + + [app:starter] + use = egg:starter + pyramid.reload_templates = true + pyramid.debug_authorization = false + pyramid.debug_notfound = false + pyramid.debug_routematch = false + pyramid.debug_templates = true + pyramid.default_locale_name = en + pyramid.tweens = pyramid.tweens.excview_tween_factory + starter.tween_factory1 + starter.tween_factory2 .. _writing_a_script: -- cgit v1.2.3 From 05f610e6ed66f8d5aca9d77ae0748feb0c8f8479 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 8 Aug 2011 23:26:59 -0400 Subject: document under and over params --- docs/narr/commandline.rst | 74 ++++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 30 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 6f969196f..0f23c153c 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -306,15 +306,16 @@ is executed. Displaying "Tweens" ------------------- -A user can get a representation of both the implicit :term:`tween` ordering -(the ordering specified by calls to -:meth:`pyramid.config.Configurator.add_tween`) and the explicit tween -ordering (specified by the ``pyramid.tweens`` configuration setting) -orderings using the ``paster ptweens`` command. Handler factories which are -functions or classes will show up as a standard Python dotted name in the -``paster ptweens`` output. Tween factories which are *instances* will show -their module and class name; the Python object id of the instance will be -appended. +A :term:`tween` is a bit of code that sits between the main Pyramid +application request handler and the WSGI application which calls it. A user +can get a representation of both the implicit tween ordering (the ordering +specified by calls to :meth:`pyramid.config.Configurator.add_tween`) and the +explicit tween ordering (specified by the ``pyramid.tweens`` configuration +setting) orderings using the ``paster ptweens`` command. Handler factories +which are functions or classes will show up as a standard Python dotted name +in the ``paster ptweens`` output. Tween factories which are *instances* will +show their module and class name; the Python object id of the instance will +be appended. For example, here's the ``paster pwteens`` command run against a system configured without any explicit tweens: @@ -322,12 +323,17 @@ configured without any explicit tweens: .. code-block:: text :linenos: - [chrism@thinko starter]$ ../bin/paster ptweens development.ini + [chrism@thinko pyramid]$ paster ptweens development.ini "pyramid.tweens" config value NOT set (implicitly ordered tweens used) - Position Name - -------- ---- - 0 pyramid.router.excview_tween_factory + Implicit Tween Chain + + Position Name Alias + -------- ---- ----- + - - INGRESS + 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory pdbt + 1 pyramid.tweens.excview_tween_factory excview + - - MAIN Here's the ``paster pwteens`` command run against a system configured *with* explicit tweens defined in its ``development.ini`` file: @@ -335,22 +341,27 @@ explicit tweens defined in its ``development.ini`` file: .. code-block:: text :linenos: - [chrism@thinko starter]$ ../bin/paster ptweens development.ini + [chrism@thinko pyramid]$ paster ptweens development.ini "pyramid.tweens" config value set (explicitly ordered tweens used) Explicit Tween Chain (used) - Position Name - -------- ---- - 0 pyramid.tweens.excview_tween_factory - 1 starter.tween_factory1 - 2 starter.tween_factory2 + Position Name + -------- ---- + - INGRESS + 0 starter.tween_factory2 + 1 starter.tween_factory1 + 2 pyramid.tweens.excview_tween_factory + - MAIN Implicit Tween Chain (not used) - Position Name - -------- ---- - 0 pyramid.tweens.excview_tween_factory + Position Name Alias + -------- ---- ----- + - - INGRESS + 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory pdbt + 1 pyramid.tweens.excview_tween_factory excview + - - MAIN Here's the application configuration section of the ``development.ini`` used by the above ``paster ptweens`` command which reprorts that the explicit @@ -361,15 +372,18 @@ tween chain is used: [app:starter] use = egg:starter - pyramid.reload_templates = true - pyramid.debug_authorization = false - pyramid.debug_notfound = false - pyramid.debug_routematch = false - pyramid.debug_templates = true - pyramid.default_locale_name = en - pyramid.tweens = pyramid.tweens.excview_tween_factory + reload_templates = true + debug_authorization = false + debug_notfound = false + debug_routematch = false + debug_templates = true + default_locale_name = en + pyramid.include = pyramid_debugtoolbar + pyramid.tweens = starter.tween_factory2 starter.tween_factory1 - starter.tween_factory2 + pyramid.tweens.excview_tween_factory + +See :ref:`registering_tweens` for more information about tweens. .. _writing_a_script: -- cgit v1.2.3