Permalink
Browse files

Merge branch 'mmerickel-feature.pshell'

  • Loading branch information...
2 parents 8cad608 + b45a606 commit d1574c723bad0e6fc0e02627a65af47af3f548c2 @mcdonc mcdonc committed Jul 10, 2011
Showing with 364 additions and 118 deletions.
  1. +5 −2 docs/api/paster.rst
  2. +63 −33 docs/narr/project.rst
  3. +5 −4 docs/narr/urldispatch.rst
  4. +6 −5 docs/narr/viewconfig.rst
  5. +109 −41 pyramid/paster.py
  6. +176 −33 pyramid/tests/test_paster.py
View
@@ -5,9 +5,12 @@
.. module:: pyramid.paster
-.. function:: get_app(config_file, name)
+.. function:: get_app(config_file, name=None)
Return the WSGI application named ``name`` in the PasteDeploy
config file ``config_file``.
-
+ If the ``name`` is None, this will attempt to parse the name from
+ the ``config_file`` string expecting the format ``ini_file#name``.
+ If no name is found, the name will default to "main".
+
View
@@ -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,48 +281,38 @@ 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
<myproject.resources.MyResource object at 0x445270>
>>> registry
<Registry myproject>
- >>> registry.settings['debug_notfound']
+ >>> settings['debug_notfound']
False
>>> from myproject.views import my_view
>>> from pyramid.request import Request
>>> r = Request.blank('/')
>>> 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 <http://en.wikipedia.org/wiki/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 <http://en.wikipedia.org/wiki/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
@@ -1084,16 +1084,17 @@ 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 two arguments. The first argument to ``proutes`` is the path
-to your application's ``.ini`` file. The second is the ``app`` section name
-inside the ``.ini`` file which points to your application.
+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
+ [chrism@thinko MyProject]$ ../bin/paster proutes development.ini#MyProject
Name Pattern View
---- ------- ----
home / <function my_view>
View
@@ -795,10 +795,11 @@ 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 three arguments. The
-first argument to ``pviews`` is the path to your application's ``.ini`` file.
-The second is the ``app`` section name inside the ``.ini`` file which points
-to your application. The third 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.
Here is an example for a simple view configuration using :term:`traversal`:
@@ -829,7 +830,7 @@ A more complex configuration might generate something like this:
.. code-block:: text
:linenos:
- $ ../bin/paster pviews development.ini shootout /about
+ $ ../bin/paster pviews development.ini#shootout /about
URL = /about
Oops, something went wrong.

0 comments on commit d1574c7

Please sign in to comment.