finish prequest feature

2 files changed, 68 insertions, 6 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 66ef46671..b9aa2c8c3 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -121,7 +121,8 @@ 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 ``pshell`` command.
+application runs "for real".  To do so, use the ``pshell`` command line
+utility.
 
 The argument to ``pshell`` follows the format ``config_file#section_name``
 where ``config_file`` is the path to your application's ``.ini`` file and
@@ -311,7 +312,7 @@ For example:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko MyProject]$ ../bin/proutes development.ini#MyProject
+   [chrism@thinko MyProject]$ ../bin/proutes development.ini
    Name            Pattern                        View
    ----            -------                        ----                     
    home            /                              <function my_view>
@@ -354,7 +355,7 @@ configured without any explicit tweens:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko pyramid]$ ptweens development.ini 
+   [chrism@thinko pyramid]$ myenv/bin/ptweens development.ini 
    "pyramid.tweens" config value NOT set (implicitly ordered tweens used)
 
    Implicit Tween Chain
@@ -416,6 +417,64 @@ is used:
 
 See :ref:`registering_tweens` for more information about tweens.
 
+.. index::
+   single: invoking a request
+   single: prequest
+
+.. _invoking_a_request:
+
+Invoking a Request
+------------------
+
+You can use the ``prequest`` command-line utility to send a request to your
+application and see the response body without starting a server.
+
+There are two required arguments to ``prequest``:
+
+- The config file/section: 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.  The
+  ``section_name`` is optional, it defaults to ``main``.  For example:
+  ``development.ini``.
+
+- The path: this should be the non-url-quoted path element of the URL to the
+  resource you'd like to be rendered on the server.  For example, ``/``.
+
+For example::
+
+   $ bin/prequest development.ini /
+
+This will print the body of the response to the console on which it was
+invoked.
+
+Several options are supported by ``prequest``.  These should precede any
+config file name or URL.
+
+``prequest`` has a ``-d`` (aka ``--display-headers``) option which prints the
+status and headers returned by the server before the output::
+
+   $ bin/prequest -d development.ini /
+
+This will print the status, then the headers, then the body of the response
+to the console.
+
+You can add request header values by using the ``--header`` option::
+
+   $ bin/prequest --header=Host=example.com development.ini /
+
+Headers are added to the WSGI environment by converting them to their
+CGI/WSGI equivalents (e.g. ``Host=example.com`` will insert the ``HTTP_HOST``
+header variable as the value ``example.com``).  Multiple ``--header`` options
+can be supplied.  The special header value ``content-type`` sets the
+``CONTENT_TYPE`` in the WSGI environment.
+
+By default, ``prequest`` sends a ``GET`` request.  You can change this by
+using the ``-m`` (aka ``--method``) option.  ``GET``, ``HEAD``, ``POST`` and
+``DELETE`` are currently supported.  When you use ``POST``, the standard
+input of the ``prequest`` process is used as the ``POST`` body::
+
+   $ bin/prequest -mPOST development.ini / < somefile
+
 .. _writing_a_script:
 
 Writing a Script
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index b0afacfe6..a69efd268 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -81,9 +81,9 @@ under both Python 2 and Python 3.  ``pcreate`` is required to be used for
 internal Pyramid scaffolding; externally distributed scaffolding may allow
 for both ``pcreate`` and/or ``paster create``.
 
-Analogues of ``paster pshell``, ``paster pviews`` and ``paster ptweens`` also
-exist under the respective console script names ``pshell``, ``pviews``, and
-``ptweens``.
+Analogues of ``paster pshell``, ``paster pviews``, ``paster request`` and
+``paster ptweens`` also exist under the respective console script names
+``pshell``, ``pviews``, ``prequest`` and ``ptweens``.
 
 We've replaced use of the Paste ``httpserver`` with the ``wsgiref`` server in
 the scaffolds, so once you create a project from a scaffold, its
@@ -296,6 +296,9 @@ Documentation Enhancements
 
 - Added a narrative docs chapter named :ref:`scaffolding_chapter`.
 
+- Added a description of the ``prequest`` command-line script at
+  :ref:`invoking_a_request`.
+
 Dependency Changes
 ------------------