diff options
| -rw-r--r-- | docs/narr/commandline.rst | 165 | ||||
| -rw-r--r-- | docs/pscripts/pcreate.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/pdistreport.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/prequest.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/proutes.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/pserve.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/pshell.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/ptweens.rst | 2 | ||||
| -rw-r--r-- | docs/pscripts/pviews.rst | 2 |
9 files changed, 118 insertions, 63 deletions
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 9e0310c29..107f35914 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -6,6 +6,63 @@ 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. +We commonly refer to this collection of utilities as "p-scripts", which is short for "Pyramid console scripts". + +Each p-script's command line usage details is available in the :ref:`pscripts_documentation`. + + +.. index:: + single: running p-scripts + pair: running; p-scripts + +.. _running-pscripts: + +Running p-scripts +----------------- + +All of the Pyramid console scripts may be run either: + +* by its name +* through a Python interpreter + + +.. index:: + single: running p-script by name + triple: p-script; running; name + +.. _running-pscripts-by-name: + +Running by ``p*`` script name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each of Pyramid's console scripts may be run by its name. For example: + +.. code-block:: bash + + $VENV/bin/pserve development.ini --reload + +.. note:: ``$VENV/bin/`` represents the ``bin`` directory in a virtual environment, where ``$VENV`` is an environment variable representing its path. + + +.. index:: + single: running p-scripts via Python + triple: p-script; running; Python + +.. _custom-arguments-to-python: + +Using Custom Arguments to Python when Running ``p*`` Scripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.5 + +Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run +using ``python3 -m``, allowing custom arguments to be sent to the +Python interpreter at runtime. For example: + +.. code-block:: bash + + python3 -m pyramid.scripts.pserve development.ini --reload + .. index:: pair: matching views; printing @@ -13,8 +70,8 @@ of command-line utilities. These utilities are documented in this chapter. .. _displaying_matching_views: -Displaying Matching Views for a Given URL ------------------------------------------ +``pviews``: Displaying Matching Views for a Given URL +----------------------------------------------------- .. seealso:: See also the output of :ref:`pviews --help <pviews_script>`. @@ -31,7 +88,7 @@ to be ``main``. Here is an example for a simple view configuration using :term:`traversal`: -.. code-block:: text +.. code-block:: bash :linenos: $VENV/bin/pviews development.ini#tutorial /FrontPage @@ -54,7 +111,7 @@ permissions and predicates that are part of that view configuration. A more complex configuration might generate something like this: -.. code-block:: text +.. code-block:: bash :linenos: $VENV/bin/pviews development.ini#shootout /about @@ -114,8 +171,8 @@ found* message. .. _interactive_shell: -The Interactive Shell ---------------------- +``pshell``: The Interactive Shell +--------------------------------- .. seealso:: See also the output of :ref:`pshell --help <pshell_script>`. @@ -144,7 +201,7 @@ have an ``[app:main]`` section that looks like so: If so, you can use the following command to invoke a debug shell using the name ``main`` as a section name: -.. code-block:: text +.. code-block:: bash $VENV/bin/pshell starter/development.ini#main Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) @@ -178,7 +235,7 @@ default :term:`root factory`, ``registry``, and ``request`` will be available. You can also simply rely on the ``main`` default section name by omitting any hash after the filename: -.. code-block:: text +.. code-block:: bash $VENV/bin/pshell starter/development.ini @@ -252,7 +309,7 @@ By defining the ``setup`` callable, we will create the module ``myapp.lib.pshell When this ``.ini`` file is loaded, the extra variable ``models`` will be available for use immediately. Since a ``setup`` callable was also specified, it is executed and new variables ``testapp``, ``tm``, and ``dbsession`` are exposed, and the request is configured to generate URLs from the host ``http://www.example.com``. For example: -.. code-block:: text +.. code-block:: bash $VENV/bin/pshell starter/development.ini Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) @@ -296,13 +353,13 @@ installed such as ``pyramid_ipython`` it will normally be auto-selected and used. You may also specifically invoke your choice with the ``-p choice`` or ``--python-shell choice`` option. -.. code-block:: text +.. code-block:: bash $VENV/bin/pshell -p ipython development.ini#MyProject You may use the ``--list-shells`` option to see the available shells. -.. code-block:: text +.. code-block:: bash $VENV/bin/pshell --list-shells Available shells: @@ -363,8 +420,8 @@ specify a list of preferred shells. .. _displaying_application_routes: -Displaying All Application Routes ---------------------------------- +``proutes``: Displaying All Application Routes +---------------------------------------------- .. seealso:: See also the output of :ref:`proutes --help <proutes_script>`. @@ -378,7 +435,7 @@ the ``section_name`` is ``main`` and can be omitted. For example: -.. code-block:: text +.. code-block:: bash :linenos: $VENV/bin/proutes development.ini @@ -415,7 +472,7 @@ and use those as defaults. For example you may remove the request method and place the view first: -.. code-block:: text +.. code-block:: ini :linenos: [proutes] @@ -425,7 +482,7 @@ For example you may remove the request method and place the view first: You can also separate the formats with commas or spaces: -.. code-block:: text +.. code-block:: ini :linenos: [proutes] @@ -446,8 +503,8 @@ include. The current available formats are ``name``, ``pattern``, ``view``, and .. _displaying_tweens: -Displaying "Tweens" -------------------- +``ptweens``: Displaying "Tweens" +-------------------------------- .. seealso:: See also the output of :ref:`ptweens --help <ptweens_script>`. @@ -462,7 +519,7 @@ standard Python dotted name in the ``ptweens`` output. For example, here's the ``ptweens`` command run against a system configured without any explicit tweens: -.. code-block:: text +.. code-block:: bash :linenos: $VENV/bin/ptweens development.ini @@ -480,10 +537,10 @@ without any explicit tweens: Here's the ``ptweens`` command run against a system configured *with* explicit tweens defined in its ``development.ini`` file: -.. code-block:: text +.. code-block:: bash :linenos: - ptweens development.ini + $VENV/bin/ptweens development.ini "pyramid.tweens" config value set (explicitly ordered tweens used) Explicit Tween Chain (used) @@ -534,8 +591,8 @@ See :ref:`registering_tweens` for more information about tweens. .. _invoking_a_request: -Invoking a Request ------------------- +``prequest``: Invoking a Request +-------------------------------- .. seealso:: See also the output of :ref:`prequest --help <prequest_script>`. @@ -553,9 +610,11 @@ There are two required arguments to ``prequest``: - 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:: +For example: + +.. code-block:: bash - $ $VENV/bin/prequest development.ini / + $VENV/bin/prequest development.ini / This will print the body of the response to the console on which it was invoked. @@ -564,16 +623,20 @@ Several options are supported by ``prequest``. These should precede any config file name or URL. ``prequest`` has a ``-d`` (i.e., ``--display-headers``) option which prints the -status and headers returned by the server before the output:: +status and headers returned by the server before the output: + +.. code-block:: bash - $ $VENV/bin/prequest -d development.ini / + $VENV/bin/prequest -d development.ini / This will print the status, headers, and the body of the response to the console. -You can add request header values by using the ``--header`` option:: +You can add request header values by using the ``--header`` option: + +.. code-block:: bash - $ $VENV/bin/prequest --header=Host:example.com development.ini / + $VENV/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 @@ -584,21 +647,11 @@ 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:: - - $ $VENV/bin/prequest -mPOST development.ini / < somefile - - -Using Custom Arguments to Python when Running ``p*`` Scripts ------------------------------------------------------------- - -.. versionadded:: 1.5 +of the ``prequest`` process is used as the ``POST`` body: -Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run -directly using ``python3 -m``, allowing custom arguments to be sent to the -Python interpreter at runtime. For example:: +.. code-block:: bash - python3 -m pyramid.scripts.pserve development.ini + $VENV/bin/prequest -mPOST development.ini / < somefile .. index:: @@ -608,8 +661,8 @@ Python interpreter at runtime. For example:: .. _showing_distributions: -Showing All Installed Distributions and Their Versions ------------------------------------------------------- +``pdistreport``: Showing All Installed Distributions and Their Versions +----------------------------------------------------------------------- .. versionadded:: 1.5 @@ -618,17 +671,19 @@ Showing All Installed Distributions and Their Versions You can use the ``pdistreport`` command to show the :app:`Pyramid` version in use, the Python version in use, and all installed versions of Python -distributions in your Python environment:: - - $ $VENV/bin/pdistreport - Pyramid version: 1.5dev - Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid - Packages: - authapp 0.0 - /home/chrism/projects/foo/src/authapp - beautifulsoup4 4.1.3 - /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg - ... more output ... +distributions in your Python environment: + +.. code-block:: bash + + $VENV/bin/pdistreport + Pyramid version: 1.5dev + Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid + Packages: + authapp 0.0 + /home/chrism/projects/foo/src/authapp + beautifulsoup4 4.1.3 + /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg + # ... more output ... ``pdistreport`` takes no options. Its output is useful to paste into a pastebin when you are having problems and need someone with more familiarity diff --git a/docs/pscripts/pcreate.rst b/docs/pscripts/pcreate.rst index c48a70acd..e2c45626a 100644 --- a/docs/pscripts/pcreate.rst +++ b/docs/pscripts/pcreate.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.pcreate:PCreateCommand.parser :prog: pcreate -.. seealso:: :ref:`creating_a_project` +.. seealso:: :ref:`creating_a_project` and :ref:`running-pscripts`. diff --git a/docs/pscripts/pdistreport.rst b/docs/pscripts/pdistreport.rst index b3c9dffd8..fa07f53ad 100644 --- a/docs/pscripts/pdistreport.rst +++ b/docs/pscripts/pdistreport.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.pdistreport:get_parser() :prog: pdistreport -.. seealso:: :ref:`showing_distributions` +.. seealso:: :ref:`showing_distributions` and :ref:`running-pscripts`. diff --git a/docs/pscripts/prequest.rst b/docs/pscripts/prequest.rst index 64ed01739..3767506fb 100644 --- a/docs/pscripts/prequest.rst +++ b/docs/pscripts/prequest.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.prequest:PRequestCommand.parser :prog: prequest -.. seealso:: :ref:`invoking_a_request` +.. seealso:: :ref:`invoking_a_request` and :ref:`running-pscripts`. diff --git a/docs/pscripts/proutes.rst b/docs/pscripts/proutes.rst index ee7c209e3..282ef327f 100644 --- a/docs/pscripts/proutes.rst +++ b/docs/pscripts/proutes.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.proutes:PRoutesCommand.parser :prog: proutes -.. seealso:: :ref:`displaying_application_routes` +.. seealso:: :ref:`displaying_application_routes` and :ref:`running-pscripts`. diff --git a/docs/pscripts/pserve.rst b/docs/pscripts/pserve.rst index 991976aea..cc3c80c91 100644 --- a/docs/pscripts/pserve.rst +++ b/docs/pscripts/pserve.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.pserve:PServeCommand.parser :prog: pserve -.. seealso:: :ref:`running_the_project_application` +.. seealso:: :ref:`running_the_project_application` and :ref:`running-pscripts`. diff --git a/docs/pscripts/pshell.rst b/docs/pscripts/pshell.rst index 4e2ce74cb..7c9050826 100644 --- a/docs/pscripts/pshell.rst +++ b/docs/pscripts/pshell.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.pshell:PShellCommand.parser :prog: pshell -.. seealso:: :ref:`interactive_shell` +.. seealso:: :ref:`interactive_shell` and :ref:`running-pscripts`. diff --git a/docs/pscripts/ptweens.rst b/docs/pscripts/ptweens.rst index f586e1467..fe9c27abd 100644 --- a/docs/pscripts/ptweens.rst +++ b/docs/pscripts/ptweens.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.ptweens:PTweensCommand.parser :prog: ptweens -.. seealso:: :ref:`displaying_tweens` +.. seealso:: :ref:`displaying_tweens` and :ref:`running-pscripts`. diff --git a/docs/pscripts/pviews.rst b/docs/pscripts/pviews.rst index da4660779..0726cb6aa 100644 --- a/docs/pscripts/pviews.rst +++ b/docs/pscripts/pviews.rst @@ -6,4 +6,4 @@ .. autoprogram:: pyramid.scripts.pviews:PViewsCommand.parser :prog: pviews -.. seealso:: :ref:`displaying_matching_views` +.. seealso:: :ref:`displaying_matching_views` and :ref:`running-pscripts`. |