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 From 391402e63c1257ede0069f220ed5a1cca1b94a9b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 13 Aug 2011 01:00:39 -0400 Subject: - Projects created via a scaffold no longer depend on the ``WebError`` package at all; configuration in the ``production.ini`` file which used to require its ``error_catcher`` middleware has been removed. Configuring error catching / email sending is now the domain of the ``pyramid_exclog`` package (see https://docs.pylonsproject.org/projects/pyramid_exclog/dev/). --- docs/narr/commandline.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 0f23c153c..b1a646aec 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -466,9 +466,14 @@ example above looks like so: .. code-block:: ini [pipeline:main] - pipeline = egg:WebError#evalerror + pipeline = translogger another + [filter:translogger] + filter_app_factory = egg:Paste#translogger + setup_console_handler = False + logger_name = wsgi + [app:another] use = egg:MyProject @@ -477,7 +482,8 @@ 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. +which is wrapped in the Paste "translogger" middleware (which logs requests +to the console). You can also specify a particular *section* of the PasteDeploy ``.ini`` file to load instead of ``main``: -- cgit v1.2.3 From 157c29002377b65834a960fd2d59c40bdd43f417 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 13 Aug 2011 06:11:26 -0400 Subject: disallow adding a tween factory which is an instance without passing its globally importable name --- docs/narr/commandline.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index b1a646aec..97004d2b8 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -311,11 +311,9 @@ 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. +setting) orderings using the ``paster ptweens`` command. Tween factories +will show up represented by their standard Python dotted name in the +``paster ptweens`` output. For example, here's the ``paster pwteens`` command run against a system configured without any explicit tweens: -- cgit v1.2.3 From fb90f0166728af40142ed9a31039d26ca3f97c73 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 14 Aug 2011 04:58:34 -0400 Subject: - The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` functions in the ``pyramid.url`` package now delegate to a method on the request they've been passed, instead of the other way around. The pyramid.request.Request object now inherits from a mixin named pyramid.url.URLMethodsMixin to make this possible, and all url/path generation logic is embedded in this mixin. - Narrative and API documentation which used the ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` functions in the ``pyramid.url`` package have now been changed to use eponymous methods of the request instead. --- 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 97004d2b8..1c9d0b15c 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -532,7 +532,7 @@ Now you can readily use Pyramid's APIs for generating URLs: .. code-block:: python - route_url('verify', env['request'], code='1337') + env['request'].route_url('verify', code='1337') # will return 'https://example.com/prefix/verify/1337' Cleanup -- cgit v1.2.3 From 33a3ead51c9ef4dcc4c4c839aae8616dcab2d3ce Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 16 Aug 2011 04:28:52 -0500 Subject: Added some docs for the new 'setup' option key in [pshell]. --- docs/narr/commandline.rst | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 1c9d0b15c..bb004c446 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -156,6 +156,7 @@ name ``MyProject`` as a section name: request Active request object. root Root of the default resource tree. root_factory Default root factory used to create `root`. + >>> root >>> registry @@ -191,12 +192,18 @@ 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 +It is 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. Each key is a variable name that will be global within the pshell session; each value is a :term:`dotted Python name`. +If specified, the special key ``setup`` should be a :term:`dotted Python name` +pointing to a callable that accepts the dictionary of globals that will +be loaded into the shell. This allows for some custom initializing code +to be executed each time the ``pshell`` is run. The ``setup`` callable +can also be specified from the commandline using the ``--setup`` option +which will override the key in the INI file. 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. @@ -206,12 +213,33 @@ Here, we'll assume your model is stored in the ``myapp.models`` package. :linenos: [pshell] + setup = myapp.lib.pshell.setup m = myapp.models session = myapp.models.DBSession t = transaction +By defining the ``setup`` callable, we will create the module +``myapp.lib.pshell`` containing a callable named ``setup`` that will receive +the global environment before it is exposed to the shell. Here we mutate the +environment's request as well as add a new value containing a WebTest version +of the application to which we can easily submit requests. + +.. code-block:: python + :linenos: + + # myapp/lib/pshell.py + from webtest import TestApp + + def setup(env): + env['request'].host = 'www.example.com' + env['request'].scheme = 'https' + env['testapp'] = TestApp(env['app']) + When this INI file is loaded, the extra variables ``m``, ``session`` and -``t`` will be available for use immediately. For example: +``t`` will be available for use immediately. Since a ``setup`` callable +was also specified, it is executed and a new variable ``testapp`` is +exposed, and the request is configured to generate urls from the host +``http://www.example.com``. For example: .. code-block:: text @@ -226,12 +254,17 @@ When this INI file is loaded, the extra variables ``m``, ``session`` and request Active request object. root Root of the default resource tree. root_factory Default root factory used to create `root`. + testapp Custom Variables: m myapp.models session myapp.models.DBSession t transaction - >>> + + >>> testapp.get('/') + <200 OK text/html body='\n'/3337> + >>> request.route_url('home') + 'https://www.example.com/' .. index:: single: IPython -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/narr/commandline.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index bb004c446..cef331e2d 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -127,12 +127,12 @@ 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. For example, if your application ``.ini`` file -might have a ``[app:MyProject]`` section that looks like so: +might have a ``[app:main]`` section that looks like so: .. code-block:: ini :linenos: - [app:MyProject] + [app:main] use = egg:MyProject pyramid.reload_templates = true pyramid.debug_authorization = false @@ -401,7 +401,7 @@ tween chain is used: .. code-block:: text :linenos: - [app:starter] + [app:main] use = egg:starter reload_templates = true debug_authorization = false -- cgit v1.2.3 From 6e3025d8d14dde9c442dae4c21bc76e57b452647 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 31 Aug 2011 11:20:54 -0400 Subject: wrong path for logging.config --- 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 cef331e2d..a8459ac27 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -593,5 +593,5 @@ use the following command: .. code-block:: python - import logging - logging.fileConfig('/path/to/my/development.ini') + import logging.config + logging.config.fileConfig('/path/to/my/development.ini') -- cgit v1.2.3 From cfb2b5596b8ef366aeef3bce5b61eafc7a2f175d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:05:29 -0400 Subject: remove all reference to the paster command-line utility --- docs/narr/commandline.rst | 70 ++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 37 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index a8459ac27..0dc41e919 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -9,7 +9,7 @@ chapter. .. index:: pair: matching views; printing - single: paster pviews + single: pviews .. _displaying_matching_views: @@ -18,9 +18,9 @@ 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 +yourself. You can use the ``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 +application. The ``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 @@ -32,7 +32,7 @@ Here is an example for a simple view configuration using :term:`traversal`: .. code-block:: text :linenos: - $ ../bin/paster pviews development.ini#tutorial /FrontPage + $ ../bin/pviews development.ini#tutorial /FrontPage URL = /FrontPage @@ -56,7 +56,7 @@ A more complex configuration might generate something like this: .. code-block:: text :linenos: - $ ../bin/paster pviews development.ini#shootout /about + $ ../bin/pviews development.ini#shootout /about URL = /about @@ -103,14 +103,13 @@ 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. +For a URL that doesn't match any views, ``pviews`` will simply print out a +*Not found* message. .. index:: single: interactive shell single: IPython - single: paster pshell single: pshell .. _interactive_shell: @@ -121,7 +120,7 @@ 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. +application runs "for real". To do so, use the ``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 @@ -145,7 +144,7 @@ name ``MyProject`` as a section name: .. code-block:: text - chrism@thinko env26]$ bin/paster pshell starter/development.ini#MyProject + chrism@thinko env26]$ bin/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. @@ -180,7 +179,7 @@ hash after the filename: .. code-block:: text - chrism@thinko env26]$ bin/paster pshell starter/development.ini + chrism@thinko env26]$ bin/pshell starter/development.ini Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). @@ -243,7 +242,7 @@ exposed, and the request is configured to generate urls from the host .. code-block:: text - chrism@thinko env26]$ bin/paster pshell starter/development.ini + chrism@thinko env26]$ bin/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. @@ -273,22 +272,20 @@ 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. +the interpreter you use to invoke the ``pshell`` command, ``pshell`` 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 \ + [chrism@vitaminf shellenv]$ ../bin/pshell --disable-ipython \ development.ini#MyProject .. index:: pair: routes; printing - single: paster proutes single: proutes .. _displaying_application_routes: @@ -296,11 +293,11 @@ unconditionally. 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 +You can use the ``proutes`` command in a terminal window to print a summary +of routes related to your application. Much like the ``pshell`` +command (see :ref:`interactive_shell`), the ``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. By default, the ``section_name`` is ``main`` and can be omitted. @@ -310,7 +307,7 @@ For example: .. code-block:: text :linenos: - [chrism@thinko MyProject]$ ../bin/paster proutes development.ini#MyProject + [chrism@thinko MyProject]$ ../bin/proutes development.ini#MyProject Name Pattern View ---- ------- ---- home / @@ -319,19 +316,18 @@ For example: static/ static/*subpath catchall /*subpath -``paster proutes`` generates a table. The table has three columns: a Name +``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 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 callable could be found. If no routes are configured within your -application, nothing will be printed to the console when ``paster proutes`` +application, nothing will be printed to the console when ``proutes`` is executed. .. index:: pair: tweens; printing - single: paster ptweens single: ptweens .. _displaying_tweens: @@ -344,17 +340,17 @@ 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. Tween factories +setting) orderings using the ``ptweens`` command. Tween factories will show up represented by their standard Python dotted name in the -``paster ptweens`` output. +``ptweens`` output. -For example, here's the ``paster pwteens`` command run against a system +For example, here's the ``pwteens`` command run against a system configured without any explicit tweens: .. code-block:: text :linenos: - [chrism@thinko pyramid]$ paster ptweens development.ini + [chrism@thinko pyramid]$ ptweens development.ini "pyramid.tweens" config value NOT set (implicitly ordered tweens used) Implicit Tween Chain @@ -366,13 +362,13 @@ configured without any explicit tweens: 1 pyramid.tweens.excview_tween_factory excview - - MAIN -Here's the ``paster pwteens`` command run against a system configured *with* +Here's the ``pwteens`` command run against a system configured *with* explicit tweens defined in its ``development.ini`` file: .. code-block:: text :linenos: - [chrism@thinko pyramid]$ paster ptweens development.ini + [chrism@thinko pyramid]$ ptweens development.ini "pyramid.tweens" config value set (explicitly ordered tweens used) Explicit Tween Chain (used) @@ -395,8 +391,8 @@ explicit tweens defined in its ``development.ini`` file: - - MAIN 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: +by the above ``ptweens`` command which reports that the explicit tween chain +is used: .. code-block:: text :linenos: -- cgit v1.2.3 From f1013bebcdd013cd1cb47cf7585c0eaa34ec3b75 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Camguilhem Date: Sat, 19 Nov 2011 16:09:41 +0100 Subject: add bpython support for pshell --- docs/narr/commandline.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 0dc41e919..dc2b75ed6 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -111,6 +111,7 @@ For a URL that doesn't match any views, ``pviews`` will simply print out a single: interactive shell single: IPython single: pshell + single: bpython .. _interactive_shell: @@ -284,6 +285,19 @@ standard Python interpreter shell unconditionally. development.ini#MyProject +bpython +~~~~~~~ + +If you have `bpython `_ installed in +the interpreter you use to invoke the ``pshell`` command, ``pshell`` will use +a bpython interactive shell instead of a standard Python if you pass the ``-b`` +or ``--enable-bpython`` flag to the ``pshell`` command. + +.. code-block:: text + + [chrism@vitaminf shellenv]$ ../bin/pshell --enable-bpython \ + development.ini#MyProject + .. index:: pair: routes; printing single: proutes -- cgit v1.2.3 From 2cf5d280866e8936b0fee0952c89ebde164337ee Mon Sep 17 00:00:00 2001 From: Jean-Philippe Camguilhem Date: Tue, 22 Nov 2011 00:20:07 +0100 Subject: add bpython support to pshell with raydeo remarks and design --- docs/narr/commandline.rst | 34 +++++++++++----------------------- 1 file changed, 11 insertions(+), 23 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index dc2b75ed6..0f0e17ca6 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -268,34 +268,22 @@ exposed, and the request is configured to generate urls from the host .. index:: single: IPython + single: bpython -IPython -~~~~~~~ - -If you have `IPython `_ installed in -the interpreter you use to invoke the ``pshell`` command, ``pshell`` 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/pshell --disable-ipython \ - development.ini#MyProject - - -bpython -~~~~~~~ +IPython or bpython +~~~~~~~~~~~~~~~~~~ -If you have `bpython `_ installed in -the interpreter you use to invoke the ``pshell`` command, ``pshell`` will use -a bpython interactive shell instead of a standard Python if you pass the ``-b`` -or ``--enable-bpython`` flag to the ``pshell`` command. +If you have `IPython `_ or +`bpython `_ or both installed in +the interpreter you use to invoke the ``pshell`` command, ``pshell`` will +autodiscover them and use the first respectively found in this order : +IPython, bpython, standard Python interpreter. However you could +specifically invoke one of your choice with the ``-p choice`` or +``--python-shell choice`` option. .. code-block:: text - [chrism@vitaminf shellenv]$ ../bin/pshell --enable-bpython \ + [chrism@vitaminf shellenv]$ ../bin/pshell -p ipython | bpython | python \ development.ini#MyProject .. index:: -- cgit v1.2.3 From d83b3943474d2eb01b0fd8c1be31c50553fd4384 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 5 Dec 2011 01:41:04 -0500 Subject: add whatsnew-1.3; garden --- docs/narr/commandline.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 0f0e17ca6..66ef46671 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -270,6 +270,8 @@ exposed, and the request is configured to generate urls from the host single: IPython single: bpython +.. _ipython_or_bpython: + IPython or bpython ~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From c8061ee1d797cb666e1d45e19765ede565d21915 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 15 Dec 2011 17:29:01 -0500 Subject: finish prequest feature --- docs/narr/commandline.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 62 insertions(+), 3 deletions(-) (limited to 'docs/narr/commandline.rst') 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 / @@ -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 -- cgit v1.2.3 From 61838b76639d6dcf9facd549841a2ed0d07ea012 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 15 Dec 2011 21:35:23 -0500 Subject: - Added a section named "Making Your Script into a Console Script" in the "Command-Line Pyramid" chapter. --- docs/narr/commandline.rst | 231 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index b9aa2c8c3..dc3cff8ac 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -654,3 +654,234 @@ use the following command: import logging.config logging.config.fileConfig('/path/to/my/development.ini') + +.. index:: + single: console script + +.. _making_a_console_script: + +Making Your Script into a Console Script +---------------------------------------- + +A "console script" is :term:`setuptools` terminology for a script that gets +installed into the ``bin`` directory of a Python :term:`virtualenv` (or +"base" Python environment) when a :term:`distribution` which houses that +script is installed. Because it's installed into the ``bin`` directory of a +virtualenv when the distribution is installed, it's a convenient way to +package and distribute functionality that you can call from the command-line. +It's often more convenient to create a console script than it is to create a +``.py`` script and instruct people to call it with "the right Python +interpreter": because it generates a file that lives in ``bin``, when it's +invoked, it will always use "the right" Python environment, which means it +will always be invoked in an environment where all the libraries it needs +(such as Pyramid) are available. + +In general, you can make your script into a console script by doing the +following: + +- Use an existing distribution (such as one you've already created via + ``pcreate``) or create a new distribution that possesses at least one + package or module. It should, within any module within the distribution, + house a callable (usually a function) that takes no arguments and which + runs any of the code you wish to run. + +- Add a ``[console_scripts]`` section to the ``entry_points`` argument of the + distribution which creates a mapping between a script name and a dotted + name representing the callable you added to your distribution. + +- Run ``setup.py develop``, ``setup.py install``, or ``easy_install`` to get + your distribution reinstalled. When you reinstall your distribution, a + file representing the script that you named in the last step will be in the + ``bin`` directory of the virtualenv in which you installed the + distribution. It will be executable. Invoking it from a terminal will + execute your callable. + +As an example, let's create some code that can be invoked by a console script +that prints the deployment settings of a Pyramid application. To do so, +we'll pretend you have a distribution with a package in it named +``myproject``. Within this package, we'll pretend you've added a +``scripts.py`` module which contains the following code: + +.. code-block:: python + :linenos: + + # myproject.scripts module + + import optparse + import sys + import textwrap + + from pyramid.paster import bootstrap + + def settings_show(): + description = """\ + Print the deployment settings for a Pyramid application. Example: + 'psettings deployment.ini' + """ + usage = "usage: %prog config_uri" + parser = optparse.OptionParser( + usage=usage, + description=textwrap.dedent(description) + ) + parser.add_option( + '-o', '--omit', + dest='omit', + metavar='PREFIX', + type='string', + action='append', + help=("Omit settings which start with PREFIX (you can use this " + "option multiple times)") + ) + + options, args = parser.parse_args(sys.argv[1:]) + if not len(args) >= 1: + print('You must provide at least one argument') + return 2 + config_uri = args[0] + omit = options.omit + if omit is None: + omit = [] + env = bootstrap(config_uri) + settings, closer = env['registry'].settings, env['closer'] + try: + for k, v in settings.items(): + if any([k.startswith(x) for x in omit]): + continue + print('%-40s %-20s' % (k, v)) + finally: + closer() + +This script uses the Python ``optparse`` module to allow us to make sense out +of extra arguments passed to the script. It uses the +:func:`pyramid.paster.bootstrap` function to get information about the the +application defined by a config file, and prints the deployment settings +defined in that config file. + +After adding this script to the package, you'll need to tell your +distribution's ``setup.py`` about its existence. Within your distribution's +top-level directory your ``setup.py`` file will look something like this: + +.. code-block:: python + :linenos: + + import os + + from setuptools import setup, find_packages + + here = os.path.abspath(os.path.dirname(__file__)) + README = open(os.path.join(here, 'README.txt')).read() + CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + + requires = ['pyramid', 'pyramid_debugtoolbar'] + + setup(name='MyProject', + version='0.0', + description='My project', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Programming Language :: Python", + "Framework :: Pylons", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web pyramid pylons', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + install_requires=requires, + tests_require=requires, + test_suite="wiggystatic", + entry_points = """\ + [paste.app_factory] + main = wiggystatic:main + """, + ) + +We're going to change the setup.py file to add an ``[console_scripts]`` +section with in the ``entry_points`` string. Within this section, you should +specify a ``scriptname = dotted.path.to:yourfunction`` line. For example:: + + [console_scripts] + show_settings = myproject.scripts:settings_show + +The ``show_settings`` name will be the name of the script that is installed +into ``bin``. The colon (``:``) between ``myproject.scripts`` and +``settings_show`` above indicates that ``myproject.scripts`` is a Python +module, and ``settings_show`` is the function in that module which contains +the code you'd like to run as the result of someone invoking the +``show_settings`` script from their command line. + +The result will be something like: + +.. code-block:: python + :linenos: + + import os + + from setuptools import setup, find_packages + + here = os.path.abspath(os.path.dirname(__file__)) + README = open(os.path.join(here, 'README.txt')).read() + CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + + requires = ['pyramid', 'pyramid_debugtoolbar'] + + setup(name='MyProject', + version='0.0', + description='My project', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Programming Language :: Python", + "Framework :: Pylons", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web pyramid pylons', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + install_requires=requires, + tests_require=requires, + test_suite="wiggystatic", + entry_points = """\ + [paste.app_factory] + main = wiggystatic:main + [console_scripts] + show_settings = myproject.scripts:settings_show + """, + ) + +Once you've done this, invoking ``$somevirtualenv/bin/python setup.py +develop`` will install a file named ``show_settings`` into the +``$somevirtualenv/bin`` directory with a small bit of Python code that points +to your entry point. It will be executable. Running it without any +arguments will print an error and exit. Running it with a single argument +that is the path of a config file will print the settings. Running it with +an ``--omit=foo`` argument will omit the settings that have keys that start +with ``foo``. Running it with two "omit" options (e.g. ``--omit=foo +--omit=bar``) will omit all settings that have keys that start with either +``foo`` or ``bar``:: + + [chrism@thinko somevenv]$ bin/show_settings development.ini \ + --omit=pyramid \ + --omit=debugtoolbar + debug_routematch False + debug_templates True + reload_templates True + mako.directories [] + debug_notfound False + default_locale_name en + reload_resources False + debug_authorization False + reload_assets False + prevent_http_cache False + +Pyramid's ``pserve``, ``pcreate``, ``pshell``, ``prequest``, ``ptweens`` and +other ``p*`` scripts are implemented as console scripts. When you invoke one +of those, you are using a console script. -- cgit v1.2.3 From 04cd4bea0457d7beeab2d2b3a1873f1e619650e8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 15 Dec 2011 22:00:01 -0500 Subject: undo cutnpaste mistakes --- docs/narr/commandline.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index dc3cff8ac..b42a7ae9e 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -793,10 +793,10 @@ top-level directory your ``setup.py`` file will look something like this: zip_safe=False, install_requires=requires, tests_require=requires, - test_suite="wiggystatic", + test_suite="myproject", entry_points = """\ [paste.app_factory] - main = wiggystatic:main + main = myproject:main """, ) @@ -848,10 +848,10 @@ The result will be something like: zip_safe=False, install_requires=requires, tests_require=requires, - test_suite="wiggystatic", + test_suite="myproject", entry_points = """\ [paste.app_factory] - main = wiggystatic:main + main = myproject:main [console_scripts] show_settings = myproject.scripts:settings_show """, -- cgit v1.2.3 From c469f2f89685dfcfe5d34a412979c807e3c35c88 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 21 Dec 2011 00:42:58 -0800 Subject: Split long run-on sentence into two. Attempt to make it more understandable, not sure of technical correctness. --- docs/narr/commandline.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index b42a7ae9e..a1fcf12f5 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -670,9 +670,9 @@ script is installed. Because it's installed into the ``bin`` directory of a virtualenv when the distribution is installed, it's a convenient way to package and distribute functionality that you can call from the command-line. It's often more convenient to create a console script than it is to create a -``.py`` script and instruct people to call it with "the right Python -interpreter": because it generates a file that lives in ``bin``, when it's -invoked, it will always use "the right" Python environment, which means it +``.py`` script and instruct people to call it with the "right" Python +interpreter. A console script generates a file that lives in ``bin``, and when it's +invoked it will always use the "right" Python environment, which means it will always be invoked in an environment where all the libraries it needs (such as Pyramid) are available. -- cgit v1.2.3 From ad3c25bac043e9d14ce8ffe1b03ae6d0e92b3b0e Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 11 Feb 2012 13:52:20 -0600 Subject: Updated the scripting example for more url control. --- docs/narr/commandline.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index a1fcf12f5..95927cfca 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -606,19 +606,21 @@ Assuming that you have a route configured in your application like so: 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: +handling requests from a certain base. For example, we want to simulate +mounting our application at `https://example.com/prefix`, to ensure that +the generated URLs are correct for our deployment. This can be done by +either mutating the resulting request object, or more simply by constructing +the desired request and passing it into :func:`~pyramid.paster.bootstrap`: .. code-block:: python from pyramid.paster import bootstrap - env = bootstrap('/path/to/my/development.ini#another') - env['request'].host = 'example.com' - env['request'].scheme = 'https' - env['request'].script_name = '/prefix' + from pyramid.request import Request + + request = Request.blank('/', base_url='https://example.com/prefix') + env = bootstrap('/path/to/my/development.ini#another', request=request) print env['request'].application_url - # will print 'https://example.com/prefix/another/url' + # will print 'https://example.com/prefix' Now you can readily use Pyramid's APIs for generating URLs: @@ -630,8 +632,8 @@ Now you can readily use Pyramid's APIs for generating URLs: Cleanup ~~~~~~~ -When your scripting logic finishes, it's good manners (but not required) to -call the ``closer`` callback: +When your scripting logic finishes, it's good manners to call the ``closer`` +callback: .. code-block:: python -- cgit v1.2.3 From 49c5838d43b377c9204375e9462ef9200660eca7 Mon Sep 17 00:00:00 2001 From: Martijn Pieters Date: Fri, 2 Mar 2012 11:51:22 +0100 Subject: Correct section name in pshell example. The section in the example is called 'app:main', not 'app:MyProject'. --- 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 95927cfca..886e075e3 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -142,11 +142,11 @@ might have a ``[app:main]`` section that looks like so: 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: +name ``main`` as a section name: .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini#MyProject + chrism@thinko env26]$ bin/pshell starter/development.ini#main Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. -- cgit v1.2.3 From 39e0d1d2b8e9bc1169c6b2f159fa16d468aaf6c5 Mon Sep 17 00:00:00 2001 From: Dan Jacka Date: Mon, 30 Apr 2012 12:46:44 +1200 Subject: Separator between name and value in --header option to prequest is ':', not '=' --- 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 886e075e3..1485caefc 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -460,7 +460,7 @@ to the console. You can add request header values by using the ``--header`` option:: - $ bin/prequest --header=Host=example.com development.ini / + $ 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`` -- cgit v1.2.3 From b9cead35e09b11c13693d6f6838b70948b568f6c Mon Sep 17 00:00:00 2001 From: Dan Jacka Date: Tue, 1 May 2012 13:33:35 +1200 Subject: Change the example script's description string to match the console_script's name: show_settings --- 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 1485caefc..4be436836 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -718,7 +718,7 @@ we'll pretend you have a distribution with a package in it named def settings_show(): description = """\ Print the deployment settings for a Pyramid application. Example: - 'psettings deployment.ini' + 'show_settings deployment.ini' """ usage = "usage: %prog config_uri" parser = optparse.OptionParser( -- cgit v1.2.3 From 0487d5e05dd61d6d7482212d40fb5884e06f582a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 12 Jun 2012 11:18:37 -0500 Subject: docs reference setup_logging instead of fileConfig --- docs/narr/commandline.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 4be436836..af53c1f78 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -654,8 +654,11 @@ use the following command: .. code-block:: python - import logging.config - logging.config.fileConfig('/path/to/my/development.ini') + import pyramid.paster + pyramid.paster.setup_logging('/path/to/my/development.ini') + +See :ref:`logging_chapter` for more information on logging within +:app:`Pyramid`. .. index:: single: console script -- cgit v1.2.3 From bad3d5184bbc9a8bc42e9d15a611b7f9f84d8131 Mon Sep 17 00:00:00 2001 From: Kees Hink Date: Tue, 14 Aug 2012 18:45:04 +0300 Subject: Typo pwteens -> ptweens --- 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 af53c1f78..3bdf8c5cd 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -349,7 +349,7 @@ setting) orderings using the ``ptweens`` command. Tween factories will show up represented by their standard Python dotted name in the ``ptweens`` output. -For example, here's the ``pwteens`` command run against a system +For example, here's the ``ptweens`` command run against a system configured without any explicit tweens: .. code-block:: text @@ -367,7 +367,7 @@ configured without any explicit tweens: 1 pyramid.tweens.excview_tween_factory excview - - MAIN -Here's the ``pwteens`` command run against a system configured *with* +Here's the ``ptweens`` command run against a system configured *with* explicit tweens defined in its ``development.ini`` file: .. code-block:: text -- cgit v1.2.3 From 08c2217e7f831379016e1ddee0b5d51eeca53878 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 1 Jan 2013 23:56:02 +0200 Subject: eliminate repeated "the" words --- 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 3bdf8c5cd..8d6b9d984 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -758,7 +758,7 @@ we'll pretend you have a distribution with a package in it named This script uses the Python ``optparse`` module to allow us to make sense out of extra arguments passed to the script. It uses the -:func:`pyramid.paster.bootstrap` function to get information about the the +:func:`pyramid.paster.bootstrap` function to get information about the application defined by a config file, and prints the deployment settings defined in that config file. -- cgit v1.2.3 From 40dbf42a2df1783c3d803adf950380c21512bb91 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 30 Jan 2013 00:41:23 +0200 Subject: use the more appropriate directives --- docs/narr/commandline.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 8d6b9d984..8e360216d 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -504,7 +504,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. +.. versionadded:: 1.1 + This feature. In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a single argument, which accepts the :term:`PasteDeploy` ``.ini`` file -- cgit v1.2.3 From 800a1f3ed76b0d4ab3895f67b6d8c35d6f392ca7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 11 Feb 2013 22:26:29 +0200 Subject: what was added? --- 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 8e360216d..0a5feafc4 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -505,7 +505,7 @@ using the :func:`pyramid.paster.bootstrap` command in the body of your script. .. versionadded:: 1.1 - This feature. + :func:`pyramid.paster.bootstrap` In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a single argument, which accepts the :term:`PasteDeploy` ``.ini`` file -- cgit v1.2.3 From 6ffabc1e9d4cf18e9cedc25bb2134ad46debd89b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 27 Feb 2013 21:05:06 +0200 Subject: readability --- docs/narr/commandline.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 0a5feafc4..48df6b9a8 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -276,10 +276,10 @@ exposed, and the request is configured to generate urls from the host IPython or bpython ~~~~~~~~~~~~~~~~~~ -If you have `IPython `_ or -`bpython `_ or both installed in +If you have `IPython `_ and/or +`bpython `_ in the interpreter you use to invoke the ``pshell`` command, ``pshell`` will -autodiscover them and use the first respectively found in this order : +autodiscover and use the first one found, in this order: IPython, bpython, standard Python interpreter. However you could specifically invoke one of your choice with the ``-p choice`` or ``--python-shell choice`` option. -- cgit v1.2.3 From eb3cee262ef52480198fc7f506debe0f35e3554a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 4 Mar 2013 22:30:32 +0200 Subject: fix #311 --- docs/narr/commandline.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 48df6b9a8..5c4d58548 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -775,8 +775,10 @@ top-level directory your ``setup.py`` file will look something like this: from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) - README = open(os.path.join(here, 'README.txt')).read() - CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + with open(os.path.join(here, 'README.txt')) as f: + README = f.read() + with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = ['pyramid', 'pyramid_debugtoolbar'] @@ -830,8 +832,10 @@ The result will be something like: from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) - README = open(os.path.join(here, 'README.txt')).read() - CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + with open(os.path.join(here, 'README.txt')) as f: + README = f.read() + with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = ['pyramid', 'pyramid_debugtoolbar'] -- cgit v1.2.3 From 5fd55bfc4eef314cab34cd485e0933e1b17bc5cf Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 01:39:35 +0200 Subject: fix wrong highlighting --- 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 5c4d58548..3fa3a1291 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -399,7 +399,7 @@ Here's the application configuration section of the ``development.ini`` used by the above ``ptweens`` command which reports that the explicit tween chain is used: -.. code-block:: text +.. code-block:: ini :linenos: [app:main] -- cgit v1.2.3 From 75e2cb6f3cfa97716a2ccd14b5ea8db72138f533 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 01:39:03 +0200 Subject: remove some clutter --- docs/narr/commandline.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 5c4d58548..8ad153187 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -146,7 +146,7 @@ name ``main`` as a section name: .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini#main + $ bin/pshell starter/development.ini#main Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. @@ -181,7 +181,7 @@ hash after the filename: .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini + $ bin/pshell starter/development.ini Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). @@ -244,7 +244,7 @@ exposed, and the request is configured to generate urls from the host .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini + $ bin/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. @@ -286,8 +286,7 @@ specifically invoke one of your choice with the ``-p choice`` or .. code-block:: text - [chrism@vitaminf shellenv]$ ../bin/pshell -p ipython | bpython | python \ - development.ini#MyProject + $ ../bin/pshell -p ipython | bpython | python development.ini#MyProject .. index:: pair: routes; printing @@ -312,7 +311,7 @@ For example: .. code-block:: text :linenos: - [chrism@thinko MyProject]$ ../bin/proutes development.ini + $ ../bin/proutes development.ini Name Pattern View ---- ------- ---- home / @@ -355,7 +354,7 @@ configured without any explicit tweens: .. code-block:: text :linenos: - [chrism@thinko pyramid]$ myenv/bin/ptweens development.ini + $ myenv/bin/ptweens development.ini "pyramid.tweens" config value NOT set (implicitly ordered tweens used) Implicit Tween Chain @@ -373,7 +372,7 @@ explicit tweens defined in its ``development.ini`` file: .. code-block:: text :linenos: - [chrism@thinko pyramid]$ ptweens development.ini + $ ptweens development.ini "pyramid.tweens" config value set (explicitly ordered tweens used) Explicit Tween Chain (used) @@ -878,9 +877,7 @@ with ``foo``. Running it with two "omit" options (e.g. ``--omit=foo --omit=bar``) will omit all settings that have keys that start with either ``foo`` or ``bar``:: - [chrism@thinko somevenv]$ bin/show_settings development.ini \ - --omit=pyramid \ - --omit=debugtoolbar + $ bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar debug_routematch False debug_templates True reload_templates True -- cgit v1.2.3 From 5a20a11be7971e2d4676a7edd46fa1789525d232 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 26 Feb 2013 22:50:13 +0200 Subject: brevity --- 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 8ad153187..c7aed595f 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -320,8 +320,8 @@ For example: static/ static/*subpath catchall /*subpath -``proutes`` generates a table. The table has three columns: a Name -column, a Pattern column, and a View column. The items listed in the +``proutes`` generates a table with three columns: *Name*, *Pattern*, +and *View*. The items listed in the 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 -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- docs/narr/commandline.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 3c922d0c3..07c892439 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -32,7 +32,7 @@ Here is an example for a simple view configuration using :term:`traversal`: .. code-block:: text :linenos: - $ ../bin/pviews development.ini#tutorial /FrontPage + $ $VENV/bin/pviews development.ini#tutorial /FrontPage URL = /FrontPage @@ -56,7 +56,7 @@ A more complex configuration might generate something like this: .. code-block:: text :linenos: - $ ../bin/pviews development.ini#shootout /about + $ $VENV/bin/pviews development.ini#shootout /about URL = /about @@ -146,7 +146,7 @@ name ``main`` as a section name: .. code-block:: text - $ bin/pshell starter/development.ini#main + $ $VENV/bin starter/development.ini#main Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. @@ -181,7 +181,7 @@ hash after the filename: .. code-block:: text - $ bin/pshell starter/development.ini + $ $VENV/bin/pshell starter/development.ini Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). @@ -244,7 +244,7 @@ exposed, and the request is configured to generate urls from the host .. code-block:: text - $ bin/pshell starter/development.ini + $ $VENV/bin/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. @@ -286,7 +286,7 @@ specifically invoke one of your choice with the ``-p choice`` or .. code-block:: text - $ ../bin/pshell -p ipython | bpython | python development.ini#MyProject + $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject .. index:: pair: routes; printing @@ -311,7 +311,7 @@ For example: .. code-block:: text :linenos: - $ ../bin/proutes development.ini + $ $VENV/bin/proutes development.ini Name Pattern View ---- ------- ---- home / @@ -354,7 +354,7 @@ configured without any explicit tweens: .. code-block:: text :linenos: - $ myenv/bin/ptweens development.ini + $ $VENV/bin/ptweens development.ini "pyramid.tweens" config value NOT set (implicitly ordered tweens used) Implicit Tween Chain @@ -441,7 +441,7 @@ There are two required arguments to ``prequest``: For example:: - $ 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. @@ -452,14 +452,14 @@ 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 / + $ $VENV/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 / + $ $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`` @@ -472,7 +472,7 @@ 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 + $ $VENV/bin/prequest -mPOST development.ini / < somefile .. _writing_a_script: @@ -866,7 +866,7 @@ The result will be something like: """, ) -Once you've done this, invoking ``$somevirtualenv/bin/python setup.py +Once you've done this, invoking ``$$VENV/bin/python setup.py develop`` will install a file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a small bit of Python code that points to your entry point. It will be executable. Running it without any @@ -877,7 +877,7 @@ with ``foo``. Running it with two "omit" options (e.g. ``--omit=foo --omit=bar``) will omit all settings that have keys that start with either ``foo`` or ``bar``:: - $ bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar + $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar debug_routematch False debug_templates True reload_templates True -- cgit v1.2.3 From 37607c3a9382de7c3757799791a91b80e2d9888d Mon Sep 17 00:00:00 2001 From: Catalin Iacob Date: Sun, 31 Mar 2013 14:33:24 +0200 Subject: Consistently link middleware term to the glossary --- docs/narr/commandline.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 07c892439..e1347f3ca 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -172,8 +172,8 @@ name ``main`` as a section name: 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 ``request`` will be +app with no surrounding :term:`middleware`, the ``root`` object returned by +the default :term:`root factory`, ``registry``, and ``request`` will be available. You can also simply rely on the ``main`` default section name by omitting any @@ -572,8 +572,8 @@ 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 Paste "translogger" middleware (which logs requests -to the console). +which is wrapped in the Paste "translogger" :term:`middleware` (which logs +requests to the console). You can also specify a particular *section* of the PasteDeploy ``.ini`` file to load instead of ``main``: -- cgit v1.2.3 From b210ce350a3856166376f63a32725cc1516ba294 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 2 Aug 2013 19:14:29 -0400 Subject: add pdistreport command --- docs/narr/commandline.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index e1347f3ca..17e5227fa 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -474,6 +474,30 @@ input of the ``prequest`` process is used as the ``POST`` body:: $ $VENV/bin/prequest -mPOST development.ini / < somefile +Showing All Installed Distributions and their Versions +------------------------------------------------------ + +.. versionadded:: 1.5 + +You can use the ``pdistreport`` command to show the 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 ... + +``pdistreport`` takes no options. Its output is useful to paste into a +pastebin when you are having problems and need someone with more familiarity +with Python packaging and distribution than you have to look at your +environment. + .. _writing_a_script: Writing a Script -- cgit v1.2.3 From edfc4f80a1240f6f5f0c41e53078a8f5d305075f Mon Sep 17 00:00:00 2001 From: Philip Jenvey Date: Thu, 15 Aug 2013 15:57:14 -0700 Subject: prefer the functionish print --- docs/narr/commandline.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 17e5227fa..58b9bdd21 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -538,7 +538,7 @@ representing Pyramid your application configuration as a single argument: from pyramid.paster import bootstrap env = bootstrap('/path/to/my/development.ini') - print env['request'].route_url('home') + print(env['request'].route_url('home')) :func:`pyramid.paster.bootstrap` returns a dictionary containing framework-related information. This dictionary will always contain a @@ -606,7 +606,7 @@ to load instead of ``main``: from pyramid.paster import bootstrap env = bootstrap('/path/to/my/development.ini#another') - print env['request'].route_url('home') + print(env['request'].route_url('home')) The above example specifies the ``another`` ``app``, ``pipeline``, or ``composite`` section of your PasteDeploy configuration file. The ``app`` @@ -643,7 +643,7 @@ the desired request and passing it into :func:`~pyramid.paster.bootstrap`: request = Request.blank('/', base_url='https://example.com/prefix') env = bootstrap('/path/to/my/development.ini#another', request=request) - print env['request'].application_url + print(env['request'].application_url) # will print 'https://example.com/prefix' Now you can readily use Pyramid's APIs for generating URLs: -- cgit v1.2.3 From 6db4eb3a5fe625918c52b40ed669f1b55343abf9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 14 Oct 2013 12:42:17 +0200 Subject: add note about custom args to python when using command-line scripts --- docs/narr/commandline.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 58b9bdd21..0984b4daf 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -474,6 +474,17 @@ 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 + +Each of Pyramid's console scripts (``pserve``, ``pviews``, etc) can be run +directly using ``python -m``, allowing custom arguments to be sent to the +python interpreter at runtime. For example:: + + python -3 -m pyramid.scripts.pserve development.ini + Showing All Installed Distributions and their Versions ------------------------------------------------------ -- cgit v1.2.3 From 1034327081839902e691236f60b2a85f74bbc4e3 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 14 Oct 2013 16:29:32 -0500 Subject: update old ptweens output --- 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 58b9bdd21..a04b38ae3 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -387,12 +387,12 @@ explicit tweens defined in its ``development.ini`` file: Implicit Tween Chain (not used) - Position Name Alias - -------- ---- ----- - - - INGRESS - 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory pdbt - 1 pyramid.tweens.excview_tween_factory excview - - - MAIN + Position Name + -------- ---- + - INGRESS + 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory + 1 pyramid.tweens.excview_tween_factory + - MAIN Here's the application configuration section of the ``development.ini`` used by the above ``ptweens`` command which reports that the explicit tween chain -- cgit v1.2.3 From 3f87c228c920edbb85a85f3332a5340063e49b11 Mon Sep 17 00:00:00 2001 From: Kamal Gill Date: Mon, 2 Jun 2014 13:51:09 -0700 Subject: Fix path to pshell --- 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 3cabbd8f4..4f16617c4 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -146,7 +146,7 @@ name ``main`` as a section name: .. code-block:: text - $ $VENV/bin starter/development.ini#main + $ $VENV/bin/pshell starter/development.ini#main Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. -- cgit v1.2.3 From 22c836ecbc6f10c4851d88017243f91e469016aa Mon Sep 17 00:00:00 2001 From: John Anderson Date: Thu, 1 Jan 2015 22:17:13 -0800 Subject: Updated the docs to talk about `--format` --- docs/narr/commandline.rst | 45 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 4f16617c4..02bb6138e 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -312,24 +312,49 @@ For example: :linenos: $ $VENV/bin/proutes development.ini - Name Pattern View - ---- ------- ---- - home / - home2 / - another /another None - static/ static/*subpath - catchall /*subpath - -``proutes`` generates a table with three columns: *Name*, *Pattern*, + Name Pattern View + ---- ------- ---- + debugtoolbar /_debug_toolbar/*subpath * + __static/ /static/*subpath dummy_starter:static/ * + __static2/ /static2/*subpath /var/www/static/ * + __pdt_images/ /pdt_images/*subpath pyramid_debugtoolbar:static/img/ * + a / * + no_view_attached / * + route_and_view_attached / app1.standard_views.route_and_view_attached * + method_conflicts /conflicts app1.standard_conflicts + multiview /multiview app1.standard_views.multiview GET,PATCH + not_post /not_post app1.standard_views.multview !POST,* + +``proutes`` generates a table with three columns: *Name*, *Pattern*, *Method*, and *View*. The items listed in the 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 +route pattern. The view column may show ```` if no associated view callable could be found. If no routes are configured within your application, nothing will be printed to the console when ``proutes`` is executed. +It is convenient when using the ``proutes`` often to configure which columns +and the order you would like to view them. To facilitate this, ``proutes`` will +look for a special ``[proutes]`` section in your INI file and use those as +defaults. + +For example you may remove request method and place the view first: + +.. code-block:: text + :linenos: + + [proutes] + format = view + name + pattern + +If you want to temporarily configure the columns and order there is the +``--format` which is a comma separated list of columns you want to include. The +current available formats are ``name``, ``pattern``, ``view``, and ``method``. + + .. index:: pair: tweens; printing single: ptweens -- cgit v1.2.3 From 83a400a3cd121fe65d33e796c28a199b35ab67e5 Mon Sep 17 00:00:00 2001 From: John Anderson Date: Thu, 1 Jan 2015 22:25:25 -0800 Subject: Terminated the highlight on ``format`` --- 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 02bb6138e..aca0ff425 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -351,7 +351,7 @@ For example you may remove request method and place the view first: pattern If you want to temporarily configure the columns and order there is the -``--format` which is a comma separated list of columns you want to include. The +``--format`` which is a comma separated list of columns you want to include. The current available formats are ``name``, ``pattern``, ``view``, and ``method``. -- cgit v1.2.3 From b8ba0f1ed25b118aeb05accb23d872b3a72dc548 Mon Sep 17 00:00:00 2001 From: John Anderson Date: Thu, 22 Jan 2015 07:29:02 -0800 Subject: Make more ways to configure [proutes] section --- docs/narr/commandline.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index aca0ff425..3dcb092e2 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -350,6 +350,17 @@ For example you may remove request method and place the view first: name pattern +You can also separate the formats with commas or spaces: + +.. code-block:: text + :linenos: + + [proutes] + format = view name pattern + + [proutes] + format = view, name, pattern + If you want to temporarily configure the columns and order there is the ``--format`` which is a comma separated list of columns you want to include. The current available formats are ``name``, ``pattern``, ``view``, and ``method``. -- cgit v1.2.3 From c7bf2744f332c0294d8d673d21b56f5edacb2eae Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 27 Jan 2015 14:51:58 -0600 Subject: fix count --- 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 3dcb092e2..1fe2d9278 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -325,7 +325,7 @@ For example: multiview /multiview app1.standard_views.multiview GET,PATCH not_post /not_post app1.standard_views.multview !POST,* -``proutes`` generates a table with three columns: *Name*, *Pattern*, *Method*, +``proutes`` generates a table with four columns: *Name*, *Pattern*, *Method*, and *View*. The items listed in the 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 -- cgit v1.2.3 From cb92023e9d0ddb56d20dcc445a5e028fec581342 Mon Sep 17 00:00:00 2001 From: John Anderson Date: Sun, 6 Sep 2015 15:26:35 -0700 Subject: Use entry points for pshell --- docs/narr/commandline.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 1fe2d9278..89df13ce4 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -288,6 +288,40 @@ specifically invoke one of your choice with the ``-p choice`` or $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject +Alternative Shells +~~~~~~~~~~~~~~~~~~ +If you want to use a shell that isn't supported out of the box you can introduce +a new shell by registering an entrypoint in your setup.py: + +.. code-block:: python + + setup( + entry_points = """\ + [pyramid.pshell] + myshell=my_app.ptpython_shell_factory + """ + ) + +and then your shell factory should return a function that accepts two arguments, +``env`` and ``help``, this would look like this: + +.. code-block:: python + + def ptpython_shell_factory(): + try: + from ptpython.repl import embed + def PTPShell(banner, **kwargs): + print(banner) + return embed(**kwargs) + except ImportError: + return None + + def shell(env, help): + PTPShell(banner=help, locals=env) + + return shell + + .. index:: pair: routes; printing single: proutes -- cgit v1.2.3 From b932a45f834ae6bdb5850a2c58d1317844b32914 Mon Sep 17 00:00:00 2001 From: John Anderson Date: Sun, 11 Oct 2015 00:50:54 -0700 Subject: removed default fall through when passed a specific shell --- docs/narr/commandline.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 89df13ce4..cb0c914d7 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -245,7 +245,7 @@ exposed, and the request is configured to generate urls from the host .. code-block:: text $ $VENV/bin/pshell starter/development.ini - Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) + Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. @@ -278,10 +278,10 @@ IPython or bpython If you have `IPython `_ and/or `bpython `_ in -the interpreter you use to invoke the ``pshell`` command, ``pshell`` will +the interpreter you use to invoke the ``pshell`` command, ``pshell`` will autodiscover and use the first one found, in this order: -IPython, bpython, standard Python interpreter. However you could -specifically invoke one of your choice with the ``-p choice`` or +IPython, bpython, standard Python interpreter. However you could +specifically invoke one of your choice with the ``-p choice`` or ``--python-shell choice`` option. .. code-block:: text @@ -308,20 +308,16 @@ and then your shell factory should return a function that accepts two arguments, .. code-block:: python def ptpython_shell_factory(): - try: - from ptpython.repl import embed - def PTPShell(banner, **kwargs): - print(banner) - return embed(**kwargs) - except ImportError: - return None + from ptpython.repl import embed + def PTPShell(banner, **kwargs): + print(banner) + return embed(**kwargs) def shell(env, help): PTPShell(banner=help, locals=env) return shell - .. index:: pair: routes; printing single: proutes -- cgit v1.2.3 From 65f9452d1a1be412ab118e6fc081dac555849cd2 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 18 Oct 2015 13:50:43 -0500 Subject: Fix entrypoints syntax in pshell as part of #1891. --- 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 cb0c914d7..641fe43cf 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -298,7 +298,7 @@ a new shell by registering an entrypoint in your setup.py: setup( entry_points = """\ [pyramid.pshell] - myshell=my_app.ptpython_shell_factory + myshell=my_app:ptpython_shell_factory """ ) -- cgit v1.2.3 From 760691509b4d85e66934e00b9ddc0c295bc2b632 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 19 Oct 2015 02:58:45 -0700 Subject: add Method sentence and heading for proutes, minor grammar, rewrap 79 cols, .rst syntax fixes --- docs/narr/commandline.rst | 479 +++++++++++++++++++++++----------------------- 1 file changed, 237 insertions(+), 242 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index cb0c914d7..dcffdb3eb 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -3,9 +3,8 @@ 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. +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 @@ -17,15 +16,15 @@ 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 ``pviews`` command in a terminal window to -print a summary of matching routes and views for a given URL in your -application. The ``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``. +configuration details in your head, even if you defined all the views yourself. +You can use the ``pviews`` command in a terminal window to print a summary of +matching routes and views for a given URL in your application. The ``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`: @@ -44,12 +43,11 @@ Here is an example for a simple view configuration using :term:`traversal`: 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. +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: @@ -99,12 +97,12 @@ A more complex configuration might generate something like this: 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. +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, ``pviews`` will simply print out a -*Not found* message. +For a URL that doesn't match any views, ``pviews`` will simply print out a *Not +found* message. .. index:: @@ -118,17 +116,16 @@ For a URL that doesn't match any views, ``pviews`` will simply print out a 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 line -utility. +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 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 ``section_name`` is the ``app`` section name inside the ``.ini`` file which -points to your application. For example, if your application ``.ini`` file -might have a ``[app:main]`` section that looks like so: +points to your application. For example, your application ``.ini`` file might +have an ``[app:main]`` section that looks like so: .. code-block:: ini :linenos: @@ -141,13 +138,13 @@ might have a ``[app:main]`` section that looks like so: 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 ``main`` as a section name: +If so, you can use the following command to invoke a debug shell using the name +``main`` as a section name: .. code-block:: text $ $VENV/bin/pshell starter/development.ini#main - Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) + Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. @@ -172,9 +169,8 @@ name ``main`` as a section name: 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 :term:`middleware`, the ``root`` object returned by -the default :term:`root factory`, ``registry``, and ``request`` will be -available. +app with no surrounding :term:`middleware`, the ``root`` object returned by the +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: @@ -193,22 +189,22 @@ Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). Extending the Shell ~~~~~~~~~~~~~~~~~~~ -It is 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. Each key is a variable name that will be -global within the pshell session; each value is a :term:`dotted Python name`. -If specified, the special key ``setup`` should be a :term:`dotted Python name` -pointing to a callable that accepts the dictionary of globals that will -be loaded into the shell. This allows for some custom initializing code -to be executed each time the ``pshell`` is run. The ``setup`` callable -can also be specified from the commandline using the ``--setup`` option -which will override the key in the INI file. - -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. +It is 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. Each key is a variable name that will be global within the pshell +session; each value is a :term:`dotted Python name`. If specified, the special +key ``setup`` should be a :term:`dotted Python name` pointing to a callable +that accepts the dictionary of globals that will be loaded into the shell. This +allows for some custom initializing code to be executed each time the +``pshell`` is run. The ``setup`` callable can also be specified from the +commandline using the ``--setup`` option which will override the key in the INI +file. + +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: @@ -236,10 +232,10 @@ of the application to which we can easily submit requests. env['request'].scheme = 'https' env['testapp'] = TestApp(env['app']) -When this INI file is loaded, the extra variables ``m``, ``session`` and -``t`` will be available for use immediately. Since a ``setup`` callable -was also specified, it is executed and a new variable ``testapp`` is -exposed, and the request is configured to generate urls from the host +When this INI file is loaded, the extra variables ``m``, ``session`` and ``t`` +will be available for use immediately. Since a ``setup`` callable was also +specified, it is executed and a new variable ``testapp`` is exposed, and the +request is configured to generate urls from the host ``http://www.example.com``. For example: .. code-block:: text @@ -276,13 +272,12 @@ exposed, and the request is configured to generate urls from the host IPython or bpython ~~~~~~~~~~~~~~~~~~ -If you have `IPython `_ and/or -`bpython `_ in -the interpreter you use to invoke the ``pshell`` command, ``pshell`` will -autodiscover and use the first one found, in this order: -IPython, bpython, standard Python interpreter. However you could -specifically invoke one of your choice with the ``-p choice`` or -``--python-shell choice`` option. +If you have `IPython `_ and/or `bpython +`_ in the interpreter you use to invoke the +``pshell`` command, ``pshell`` will autodiscover and use the first one found, +in this order: IPython, bpython, standard Python interpreter. However you could +specifically invoke your choice with the ``-p choice`` or ``--python-shell +choice`` option. .. code-block:: text @@ -290,8 +285,8 @@ specifically invoke one of your choice with the ``-p choice`` or Alternative Shells ~~~~~~~~~~~~~~~~~~ -If you want to use a shell that isn't supported out of the box you can introduce -a new shell by registering an entrypoint in your setup.py: +If you want to use a shell that isn't supported out of the box, you can +introduce a new shell by registering an entry point in your setup.py: .. code-block:: python @@ -302,8 +297,8 @@ a new shell by registering an entrypoint in your setup.py: """ ) -and then your shell factory should return a function that accepts two arguments, -``env`` and ``help``, this would look like this: +And then your shell factory should return a function that accepts two +arguments, ``env`` and ``help``, which would look like this: .. code-block:: python @@ -318,6 +313,8 @@ and then your shell factory should return a function that accepts two arguments, return shell +.. versionadded:: 1.6 + .. index:: pair: routes; printing single: proutes @@ -327,14 +324,13 @@ and then your shell factory should return a function that accepts two arguments, Displaying All Application Routes --------------------------------- -You can use the ``proutes`` command in a terminal window to print a summary -of routes related to your application. Much like the ``pshell`` -command (see :ref:`interactive_shell`), the ``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. By default, the ``section_name`` is ``main`` and -can be omitted. +You can use the ``proutes`` command in a terminal window to print a summary of +routes related to your application. Much like the ``pshell`` command (see +:ref:`interactive_shell`), the ``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. By default, +the ``section_name`` is ``main`` and can be omitted. For example: @@ -342,8 +338,8 @@ For example: :linenos: $ $VENV/bin/proutes development.ini - Name Pattern View - ---- ------- ---- + Name Pattern View Method + ---- ------- ---- ------ debugtoolbar /_debug_toolbar/*subpath * __static/ /static/*subpath dummy_starter:static/ * __static2/ /static2/*subpath /var/www/static/ * @@ -355,22 +351,25 @@ For example: multiview /multiview app1.standard_views.multiview GET,PATCH not_post /not_post app1.standard_views.multview !POST,* -``proutes`` generates a table with four columns: *Name*, *Pattern*, *Method*, -and *View*. The items listed in the -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 ```` if no associated view -callable could be found. If no routes are configured within your -application, nothing will be printed to the console when ``proutes`` -is executed. - -It is convenient when using the ``proutes`` often to configure which columns -and the order you would like to view them. To facilitate this, ``proutes`` will -look for a special ``[proutes]`` section in your INI file and use those as -defaults. - -For example you may remove request method and place the view first: +``proutes`` generates a table with four columns: *Name*, *Pattern*, *View*, and +*Method*. The items listed in the Name column are route names, the items +listed in the Pattern column are route patterns, 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, and the items listed in the +Method column are the request methods that are associated with the route name. +The View column may show ```` if no associated view callable could be +found. The Method column, for the route name, may show either ```` if the view callable does not accept any of the route's request +methods, or ``*`` if the view callable will accept any of the route's request +methods. If no routes are configured within your application, nothing will be +printed to the console when ``proutes`` is executed. + +It is convenient when using the ``proutes`` command often to configure which +columns and the order you would like to view them. To facilitate this, +``proutes`` will look for a special ``[proutes]`` section in your ``.ini`` file +and use those as defaults. + +For example you may remove the request method and place the view first: .. code-block:: text :linenos: @@ -391,9 +390,10 @@ You can also separate the formats with commas or spaces: [proutes] format = view, name, pattern -If you want to temporarily configure the columns and order there is the -``--format`` which is a comma separated list of columns you want to include. The -current available formats are ``name``, ``pattern``, ``view``, and ``method``. +If you want to temporarily configure the columns and order, there is the +argument ``--format``, which is a comma separated list of columns you want to +include. The current available formats are ``name``, ``pattern``, ``view``, and +``method``. .. index:: @@ -405,17 +405,16 @@ current available formats are ``name``, ``pattern``, ``view``, and ``method``. Displaying "Tweens" ------------------- -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 ``ptweens`` command. Tween factories -will show up represented by their standard Python dotted name in the -``ptweens`` output. +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) using the +``ptweens`` command. Tween factories will show up represented by their +standard Python dotted name in the ``ptweens`` output. -For example, here's the ``ptweens`` command run against a system -configured without any explicit tweens: +For example, here's the ``ptweens`` command run against a system configured +without any explicit tweens: .. code-block:: text :linenos: @@ -425,15 +424,15 @@ configured without any explicit tweens: Implicit Tween Chain - Position Name Alias + Position Name Alias -------- ---- ----- - - INGRESS 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory pdbt 1 pyramid.tweens.excview_tween_factory excview - - MAIN -Here's the ``ptweens`` command run against a system configured *with* -explicit tweens defined in its ``development.ini`` file: +Here's the ``ptweens`` command run against a system configured *with* explicit +tweens defined in its ``development.ini`` file: .. code-block:: text :linenos: @@ -443,13 +442,13 @@ explicit tweens defined in its ``development.ini`` file: Explicit Tween Chain (used) - Position Name - -------- ---- - - INGRESS - 0 starter.tween_factory2 - 1 starter.tween_factory1 - 2 pyramid.tweens.excview_tween_factory - - MAIN + Position Name + -------- ---- + - INGRESS + 0 starter.tween_factory2 + 1 starter.tween_factory1 + 2 pyramid.tweens.excview_tween_factory + - MAIN Implicit Tween Chain (not used) @@ -460,9 +459,9 @@ explicit tweens defined in its ``development.ini`` file: 1 pyramid.tweens.excview_tween_factory - MAIN -Here's the application configuration section of the ``development.ini`` used -by the above ``ptweens`` command which reports that the explicit tween chain -is used: +Here's the application configuration section of the ``development.ini`` used by +the above ``ptweens`` command which reports that the explicit tween chain is +used: .. code-block:: ini :linenos: @@ -496,13 +495,13 @@ 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`` +- 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: + ``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 +- 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:: @@ -512,31 +511,31 @@ For example:: 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. +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 +``prequest`` has a ``-d`` (i.e., ``--display-headers``) option which prints the status and headers returned by the server before the output:: $ $VENV/bin/prequest -d development.ini / -This will print the status, then the headers, then the body of the response -to the console. +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:: $ $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 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. +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:: +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 @@ -545,28 +544,28 @@ Using Custom Arguments to Python when Running ``p*`` Scripts .. versionadded:: 1.5 -Each of Pyramid's console scripts (``pserve``, ``pviews``, etc) can be run +Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run directly using ``python -m``, allowing custom arguments to be sent to the -python interpreter at runtime. For example:: +Python interpreter at runtime. For example:: python -3 -m pyramid.scripts.pserve development.ini -Showing All Installed Distributions and their Versions +Showing All Installed Distributions and Their Versions ------------------------------------------------------ .. versionadded:: 1.5 -You can use the ``pdistreport`` command to show the Pyramid version in use, the -Python version in use, and all installed versions of Python distributions in -your Python environment:: +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 + 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 ... @@ -581,35 +580,33 @@ 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 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. +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 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. 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. +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. +using the :func:`pyramid.paster.bootstrap` command in the body of your script. .. versionadded:: 1.1 :func:`pyramid.paster.bootstrap` 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: +representing your Pyramid application's configuration as a single argument: .. code-block:: python @@ -645,14 +642,13 @@ registry 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. + 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: +Let's assume that the ``/path/to/my/development.ini`` file used in the example +above looks like so: .. code-block:: ini @@ -669,15 +665,15 @@ example above looks like so: 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 Paste "translogger" :term:`middleware` (which logs -requests to the console). +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 Paste "translogger" :term:`middleware` (which logs requests to the +console). -You can also specify a particular *section* of the PasteDeploy ``.ini`` file -to load instead of ``main``: +You can also specify a particular *section* of the PasteDeploy ``.ini`` file to +load instead of ``main``: .. code-block:: python @@ -694,9 +690,9 @@ Changing the Request ~~~~~~~~~~~~~~~~~~~~ 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. +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. So how do we make Pyramid generate the correct URLs? @@ -708,10 +704,10 @@ Assuming that you have a route configured in your application like so: You need to inform the Pyramid environment that the WSGI application is handling requests from a certain base. For example, we want to simulate -mounting our application at `https://example.com/prefix`, to ensure that -the generated URLs are correct for our deployment. This can be done by -either mutating the resulting request object, or more simply by constructing -the desired request and passing it into :func:`~pyramid.paster.bootstrap`: +mounting our application at `https://example.com/prefix`, to ensure that the +generated URLs are correct for our deployment. This can be done by either +mutating the resulting request object, or more simply by constructing the +desired request and passing it into :func:`~pyramid.paster.bootstrap`: .. code-block:: python @@ -770,43 +766,43 @@ Making Your Script into a Console Script ---------------------------------------- A "console script" is :term:`setuptools` terminology for a script that gets -installed into the ``bin`` directory of a Python :term:`virtualenv` (or -"base" Python environment) when a :term:`distribution` which houses that -script is installed. Because it's installed into the ``bin`` directory of a -virtualenv when the distribution is installed, it's a convenient way to -package and distribute functionality that you can call from the command-line. -It's often more convenient to create a console script than it is to create a -``.py`` script and instruct people to call it with the "right" Python -interpreter. A console script generates a file that lives in ``bin``, and when it's -invoked it will always use the "right" Python environment, which means it -will always be invoked in an environment where all the libraries it needs -(such as Pyramid) are available. +installed into the ``bin`` directory of a Python :term:`virtualenv` (or "base" +Python environment) when a :term:`distribution` which houses that script is +installed. Because it's installed into the ``bin`` directory of a virtualenv +when the distribution is installed, it's a convenient way to package and +distribute functionality that you can call from the command-line. It's often +more convenient to create a console script than it is to create a ``.py`` +script and instruct people to call it with the "right" Python interpreter. A +console script generates a file that lives in ``bin``, and when it's invoked it +will always use the "right" Python environment, which means it will always be +invoked in an environment where all the libraries it needs (such as Pyramid) +are available. In general, you can make your script into a console script by doing the following: - Use an existing distribution (such as one you've already created via - ``pcreate``) or create a new distribution that possesses at least one - package or module. It should, within any module within the distribution, - house a callable (usually a function) that takes no arguments and which - runs any of the code you wish to run. + ``pcreate``) or create a new distribution that possesses at least one package + or module. It should, within any module within the distribution, house a + callable (usually a function) that takes no arguments and which runs any of + the code you wish to run. - Add a ``[console_scripts]`` section to the ``entry_points`` argument of the - distribution which creates a mapping between a script name and a dotted - name representing the callable you added to your distribution. + distribution which creates a mapping between a script name and a dotted name + representing the callable you added to your distribution. - Run ``setup.py develop``, ``setup.py install``, or ``easy_install`` to get - your distribution reinstalled. When you reinstall your distribution, a - file representing the script that you named in the last step will be in the - ``bin`` directory of the virtualenv in which you installed the - distribution. It will be executable. Invoking it from a terminal will - execute your callable. + your distribution reinstalled. When you reinstall your distribution, a file + representing the script that you named in the last step will be in the + ``bin`` directory of the virtualenv in which you installed the distribution. + It will be executable. Invoking it from a terminal will execute your + callable. As an example, let's create some code that can be invoked by a console script -that prints the deployment settings of a Pyramid application. To do so, -we'll pretend you have a distribution with a package in it named -``myproject``. Within this package, we'll pretend you've added a -``scripts.py`` module which contains the following code: +that prints the deployment settings of a Pyramid application. To do so, we'll +pretend you have a distribution with a package in it named ``myproject``. +Within this package, we'll pretend you've added a ``scripts.py`` module which +contains the following code: .. code-block:: python :linenos: @@ -865,7 +861,7 @@ defined in that config file. After adding this script to the package, you'll need to tell your distribution's ``setup.py`` about its existence. Within your distribution's -top-level directory your ``setup.py`` file will look something like this: +top-level directory, your ``setup.py`` file will look something like this: .. code-block:: python :linenos: @@ -908,9 +904,9 @@ top-level directory your ``setup.py`` file will look something like this: """, ) -We're going to change the setup.py file to add an ``[console_scripts]`` -section with in the ``entry_points`` string. Within this section, you should -specify a ``scriptname = dotted.path.to:yourfunction`` line. For example:: +We're going to change the setup.py file to add a ``[console_scripts]`` section +within the ``entry_points`` string. Within this section, you should specify a +``scriptname = dotted.path.to:yourfunction`` line. For example:: [console_scripts] show_settings = myproject.scripts:settings_show @@ -918,9 +914,9 @@ specify a ``scriptname = dotted.path.to:yourfunction`` line. For example:: The ``show_settings`` name will be the name of the script that is installed into ``bin``. The colon (``:``) between ``myproject.scripts`` and ``settings_show`` above indicates that ``myproject.scripts`` is a Python -module, and ``settings_show`` is the function in that module which contains -the code you'd like to run as the result of someone invoking the -``show_settings`` script from their command line. +module, and ``settings_show`` is the function in that module which contains the +code you'd like to run as the result of someone invoking the ``show_settings`` +script from their command line. The result will be something like: @@ -967,29 +963,28 @@ The result will be something like: """, ) -Once you've done this, invoking ``$$VENV/bin/python setup.py -develop`` will install a file named ``show_settings`` into the -``$somevirtualenv/bin`` directory with a small bit of Python code that points -to your entry point. It will be executable. Running it without any -arguments will print an error and exit. Running it with a single argument -that is the path of a config file will print the settings. Running it with -an ``--omit=foo`` argument will omit the settings that have keys that start -with ``foo``. Running it with two "omit" options (e.g. ``--omit=foo ---omit=bar``) will omit all settings that have keys that start with either -``foo`` or ``bar``:: +Once you've done this, invoking ``$$VENV/bin/python setup.py develop`` will +install a file named ``show_settings`` into the ``$somevirtualenv/bin`` +directory with a small bit of Python code that points to your entry point. It +will be executable. Running it without any arguments will print an error and +exit. Running it with a single argument that is the path of a config file will +print the settings. Running it with an ``--omit=foo`` argument will omit the +settings that have keys that start with ``foo``. Running it with two "omit" +options (e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys +that start with either ``foo`` or ``bar``:: $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar - debug_routematch False - debug_templates True - reload_templates True - mako.directories [] - debug_notfound False - default_locale_name en - reload_resources False - debug_authorization False - reload_assets False - prevent_http_cache False - -Pyramid's ``pserve``, ``pcreate``, ``pshell``, ``prequest``, ``ptweens`` and + debug_routematch False + debug_templates True + reload_templates True + mako.directories [] + debug_notfound False + default_locale_name en + reload_resources False + debug_authorization False + reload_assets False + prevent_http_cache False + +Pyramid's ``pserve``, ``pcreate``, ``pshell``, ``prequest``, ``ptweens``, and other ``p*`` scripts are implemented as console scripts. When you invoke one of those, you are using a console script. -- cgit v1.2.3 From 208e7b5e363b07476797d9f754962982c686e907 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 19 Oct 2015 23:44:17 -0500 Subject: add pshell --list and default_shell ini options --- docs/narr/commandline.rst | 59 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 14 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 9db92b669..c3791adf2 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -269,32 +269,39 @@ request is configured to generate urls from the host .. _ipython_or_bpython: -IPython or bpython +Alternative Shells ~~~~~~~~~~~~~~~~~~ - If you have `IPython `_ and/or `bpython `_ in the interpreter you use to invoke the -``pshell`` command, ``pshell`` will autodiscover and use the first one found, -in this order: IPython, bpython, standard Python interpreter. However you could -specifically invoke your choice with the ``-p choice`` or ``--python-shell -choice`` option. +``pshell`` command, ``pshell`` will autodiscover and use the first one found. +However you could specifically invoke your choice with the ``-p choice`` or +``--python-shell choice`` option. .. code-block:: text - $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject + $ $VENV/bin/pshell -p ipython development.ini#MyProject + +You may use the ``--list-shells`` option to see the available shells. + +.. code-block:: text + + $ $VENV/bin/pshell --list-shells + Available shells: + bpython [not available] + ipython + python -Alternative Shells -~~~~~~~~~~~~~~~~~~ If you want to use a shell that isn't supported out of the box, you can introduce a new shell by registering an entry point in your setup.py: .. code-block:: python setup( - entry_points = """\ - [pyramid.pshell] - myshell=my_app:ptpython_shell_factory - """ + entry_points={ + 'pyramid.pshell': [ + 'myshell=my_app:ptpython_shell_factory', + ], + }, ) And then your shell factory should return a function that accepts two @@ -303,7 +310,12 @@ arguments, ``env`` and ``help``, which would look like this: .. code-block:: python def ptpython_shell_factory(): - from ptpython.repl import embed + try: + from ptpython.repl import embed + except ImportError: + # ptpython is not installed + return None + def PTPShell(banner, **kwargs): print(banner) return embed(**kwargs) @@ -313,6 +325,25 @@ arguments, ``env`` and ``help``, which would look like this: return shell +If the factory returns ``None`` then it is assumed that the shell is not +supported. + +.. versionchanged:: 1.6 + User-defined shells may be registered using entry points. Prior to this + the only supported shells were ``ipython``, ``bpython`` and ``python``. + +Setting a Default Shell +~~~~~~~~~~~~~~~~~~~~~~~ + +You may use the ``default_shell`` option in your ``[pshell]`` ini section to +specify a list of preferred shells. + +.. code-block:: ini + :linenos: + + [pshell] + default_shell = ptpython ipython bpython + .. versionadded:: 1.6 .. index:: -- cgit v1.2.3 From b7350ee78ad4101ea4112741ab26ce583b620ea7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 21 Oct 2015 01:32:48 -0500 Subject: remove ipython and bpython from core --- docs/narr/commandline.rst | 43 +++++++++++++------------------------------ 1 file changed, 13 insertions(+), 30 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index c3791adf2..d466bed44 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -107,9 +107,7 @@ found* message. .. index:: single: interactive shell - single: IPython single: pshell - single: bpython .. _interactive_shell: @@ -263,18 +261,13 @@ request is configured to generate urls from the host >>> request.route_url('home') 'https://www.example.com/' -.. index:: - single: IPython - single: bpython - -.. _ipython_or_bpython: - Alternative Shells ~~~~~~~~~~~~~~~~~~ -If you have `IPython `_ and/or `bpython -`_ in the interpreter you use to invoke the -``pshell`` command, ``pshell`` will autodiscover and use the first one found. -However you could specifically invoke your choice with the ``-p choice`` or + +The ``pshell`` command can be easily extended with alternate REPLs if the +default python REPL is not satisfactory. Assuming you have a binding +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 @@ -287,7 +280,7 @@ You may use the ``--list-shells`` option to see the available shells. $ $VENV/bin/pshell --list-shells Available shells: - bpython [not available] + bpython ipython python @@ -309,29 +302,19 @@ arguments, ``env`` and ``help``, which would look like this: .. code-block:: python - def ptpython_shell_factory(): - try: - from ptpython.repl import embed - except ImportError: - # ptpython is not installed - return None + from ptpython.repl import embed - def PTPShell(banner, **kwargs): - print(banner) - return embed(**kwargs) - - def shell(env, help): - PTPShell(banner=help, locals=env) - - return shell - -If the factory returns ``None`` then it is assumed that the shell is not -supported. + def ptpython_shell_runner(env, help): + print(help) + return embed(locals=env) .. versionchanged:: 1.6 User-defined shells may be registered using entry points. Prior to this the only supported shells were ``ipython``, ``bpython`` and ``python``. + ``ipython`` and ``bpython`` have been moved into their respective + packages ``pyramid_ipython`` and ``pyramid_bpython``. + Setting a Default Shell ~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From aac38eab09547d5dfb11ff00128c3aab91e947ac Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 22 Oct 2015 21:58:47 -0500 Subject: fix entry point example --- 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 d466bed44..430641a50 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -291,7 +291,7 @@ introduce a new shell by registering an entry point in your setup.py: setup( entry_points={ - 'pyramid.pshell': [ + 'pyramid.pshell_runner': [ 'myshell=my_app:ptpython_shell_factory', ], }, -- cgit v1.2.3 From 4429b543d97712dbec1ce10e3489385ff16a3639 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Tue, 27 Oct 2015 12:23:15 -0400 Subject: Restore link target used by 'whatsnew-1.3.rst'. Should fix Jenkins breakage. --- docs/narr/commandline.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 430641a50..eb79dffb6 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -261,6 +261,8 @@ request is configured to generate urls from the host >>> request.route_url('home') 'https://www.example.com/' +.. _ipython_or_bpython: + Alternative Shells ~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 5ff3d2dfdbf936d115e3486696401ad7dbffedc3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Dec 2015 01:24:34 -0800 Subject: - add p* scripts - add links to p* scripts - add a blank line to keep indices and labels better visually related to the subsequent heading --- docs/narr/commandline.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index eb79dffb6..34b12e1e9 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -6,6 +6,7 @@ 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: pviews @@ -15,6 +16,8 @@ of command-line utilities. These utilities are documented in this chapter. Displaying Matching Views for a Given URL ----------------------------------------- +.. seealso:: See also the output of :ref:`pviews --help `. + 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 ``pviews`` command in a terminal window to print a summary of @@ -114,6 +117,8 @@ found* message. The Interactive Shell --------------------- +.. seealso:: See also the output of :ref:`pshell --help `. + 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 @@ -179,6 +184,7 @@ hash after the filename: Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). + .. index:: pair: pshell; extending @@ -261,6 +267,7 @@ request is configured to generate urls from the host >>> request.route_url('home') 'https://www.example.com/' + .. _ipython_or_bpython: Alternative Shells @@ -317,6 +324,7 @@ arguments, ``env`` and ``help``, which would look like this: ``ipython`` and ``bpython`` have been moved into their respective packages ``pyramid_ipython`` and ``pyramid_bpython``. + Setting a Default Shell ~~~~~~~~~~~~~~~~~~~~~~~ @@ -331,6 +339,7 @@ specify a list of preferred shells. .. versionadded:: 1.6 + .. index:: pair: routes; printing single: proutes @@ -340,6 +349,8 @@ specify a list of preferred shells. Displaying All Application Routes --------------------------------- +.. seealso:: See also the output of :ref:`proutes --help `. + You can use the ``proutes`` command in a terminal window to print a summary of routes related to your application. Much like the ``pshell`` command (see :ref:`interactive_shell`), the ``proutes`` command accepts one argument with @@ -421,6 +432,8 @@ include. The current available formats are ``name``, ``pattern``, ``view``, and Displaying "Tweens" ------------------- +.. seealso:: See also the output of :ref:`ptweens --help `. + 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 @@ -497,6 +510,7 @@ used: See :ref:`registering_tweens` for more information about tweens. + .. index:: single: invoking a request single: prequest @@ -506,6 +520,8 @@ See :ref:`registering_tweens` for more information about tweens. Invoking a Request ------------------ +.. seealso:: See also the output of :ref:`prequest --help `. + You can use the ``prequest`` command-line utility to send a request to your application and see the response body without starting a server. @@ -555,6 +571,7 @@ 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 ------------------------------------------------------------ @@ -566,11 +583,22 @@ Python interpreter at runtime. For example:: python -3 -m pyramid.scripts.pserve development.ini + +.. index:: + single: pdistreport + single: distributions, showing installed + single: showing installed distributions + +.. _showing_distributions: + Showing All Installed Distributions and Their Versions ------------------------------------------------------ .. versionadded:: 1.5 +.. seealso:: See also the output of :ref:`pdistreport --help + `. + 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:: @@ -590,6 +618,7 @@ pastebin when you are having problems and need someone with more familiarity with Python packaging and distribution than you have to look at your environment. + .. _writing_a_script: Writing a Script @@ -702,6 +731,7 @@ The above example specifies the ``another`` ``app``, ``pipeline``, or object present in the ``env`` dictionary returned by :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`. + Changing the Request ~~~~~~~~~~~~~~~~~~~~ @@ -742,6 +772,7 @@ Now you can readily use Pyramid's APIs for generating URLs: env['request'].route_url('verify', code='1337') # will return 'https://example.com/prefix/verify/1337' + Cleanup ~~~~~~~ @@ -757,6 +788,7 @@ callback: env['closer']() + Setting Up Logging ~~~~~~~~~~~~~~~~~~ @@ -773,6 +805,7 @@ use the following command: See :ref:`logging_chapter` for more information on logging within :app:`Pyramid`. + .. index:: single: console script -- cgit v1.2.3 From a624d56914ed9e10e3c0e8bb34a84700e78bcaf6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 10 Apr 2016 03:35:48 -0700 Subject: - update commandline.rst to use pip --- docs/narr/commandline.rst | 90 ++++++++++++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 36 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 34b12e1e9..bc04f4c7a 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -119,7 +119,7 @@ The Interactive Shell .. seealso:: See also the output of :ref:`pshell --help `. -Once you've installed your program for development using ``setup.py develop``, +Once you've installed your program for development using ``pip install -e .``, 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 line utility. @@ -294,7 +294,7 @@ You may use the ``--list-shells`` option to see the available shells. python If you want to use a shell that isn't supported out of the box, you can -introduce a new shell by registering an entry point in your setup.py: +introduce a new shell by registering an entry point in your ``setup.py``: .. code-block:: python @@ -840,12 +840,11 @@ following: distribution which creates a mapping between a script name and a dotted name representing the callable you added to your distribution. -- Run ``setup.py develop``, ``setup.py install``, or ``easy_install`` to get - your distribution reinstalled. When you reinstall your distribution, a file - representing the script that you named in the last step will be in the - ``bin`` directory of the virtualenv in which you installed the distribution. - It will be executable. Invoking it from a terminal will execute your - callable. +- Run ``pip install -e .`` or ``pip install .`` to get your distribution + reinstalled. When you reinstall your distribution, a file representing the + script that you named in the last step will be in the ``bin`` directory of + the virtualenv in which you installed the distribution. It will be + executable. Invoking it from a terminal will execute your callable. As an example, let's create some code that can be invoked by a console script that prints the deployment settings of a Pyramid application. To do so, we'll @@ -927,16 +926,22 @@ top-level directory, your ``setup.py`` file will look something like this: requires = ['pyramid', 'pyramid_debugtoolbar'] + testing_extras = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', # includes virtualenv + 'pytest-cov', + ] + setup(name='MyProject', version='0.0', description='My project', long_description=README + '\n\n' + CHANGES, classifiers=[ - "Programming Language :: Python", - "Framework :: Pylons", - "Topic :: Internet :: WWW/HTTP", - "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", - ], + "Programming Language :: Python", + "Framework :: Pyramid", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], author='', author_email='', url='', @@ -945,20 +950,23 @@ top-level directory, your ``setup.py`` file will look something like this: include_package_data=True, zip_safe=False, install_requires=requires, - tests_require=requires, - test_suite="myproject", + extras_require={ + 'testing': testing_extras, + }, entry_points = """\ [paste.app_factory] main = myproject:main """, ) -We're going to change the setup.py file to add a ``[console_scripts]`` section -within the ``entry_points`` string. Within this section, you should specify a -``scriptname = dotted.path.to:yourfunction`` line. For example:: +We're going to change the ``setup.py`` file to add a ``[console_scripts]`` +section within the ``entry_points`` string. Within this section, you should +specify a ``scriptname = dotted.path.to:yourfunction`` line. For example: + +.. code-block:: ini - [console_scripts] - show_settings = myproject.scripts:settings_show + [console_scripts] + show_settings = myproject.scripts:settings_show The ``show_settings`` name will be the name of the script that is installed into ``bin``. The colon (``:``) between ``myproject.scripts`` and @@ -971,6 +979,7 @@ The result will be something like: .. code-block:: python :linenos: + :emphasize-lines: 43-44 import os @@ -984,16 +993,22 @@ The result will be something like: requires = ['pyramid', 'pyramid_debugtoolbar'] + testing_extras = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', # includes virtualenv + 'pytest-cov', + ] + setup(name='MyProject', version='0.0', description='My project', long_description=README + '\n\n' + CHANGES, classifiers=[ - "Programming Language :: Python", - "Framework :: Pylons", - "Topic :: Internet :: WWW/HTTP", - "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", - ], + "Programming Language :: Python", + "Framework :: Pyramid", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], author='', author_email='', url='', @@ -1002,8 +1017,9 @@ The result will be something like: include_package_data=True, zip_safe=False, install_requires=requires, - tests_require=requires, - test_suite="myproject", + extras_require={ + 'testing': testing_extras, + }, entry_points = """\ [paste.app_factory] main = myproject:main @@ -1012,15 +1028,17 @@ The result will be something like: """, ) -Once you've done this, invoking ``$$VENV/bin/python setup.py develop`` will -install a file named ``show_settings`` into the ``$somevirtualenv/bin`` -directory with a small bit of Python code that points to your entry point. It -will be executable. Running it without any arguments will print an error and -exit. Running it with a single argument that is the path of a config file will -print the settings. Running it with an ``--omit=foo`` argument will omit the -settings that have keys that start with ``foo``. Running it with two "omit" -options (e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys -that start with either ``foo`` or ``bar``:: +Once you've done this, invoking ``$VENV/bin/pip install -e .`` will install a +file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a +small bit of Python code that points to your entry point. It will be +executable. Running it without any arguments will print an error and exit. +Running it with a single argument that is the path of a config file will print +the settings. Running it with an ``--omit=foo`` argument will omit the settings +that have keys that start with ``foo``. Running it with two "omit" options +(e.g., ``--omit=foo --omit=bar``) will omit all settings that have keys that +start with either ``foo`` or ``bar``: + +.. code-block:: bash $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar debug_routematch False -- cgit v1.2.3 From b485166239091c620c96ca71369c69f6fa7a8be7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 02:51:20 -0700 Subject: - replace `python -m` with `python3 -m` --- 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 bc04f4c7a..3e164ee8d 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -578,10 +578,10 @@ Using Custom Arguments to Python when Running ``p*`` Scripts .. versionadded:: 1.5 Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run -directly using ``python -m``, allowing custom arguments to be sent to the +directly using ``python3 -m``, allowing custom arguments to be sent to the Python interpreter at runtime. For example:: - python -3 -m pyramid.scripts.pserve development.ini + python3 -m pyramid.scripts.pserve development.ini .. index:: -- cgit v1.2.3 From ebbe68144ad6a6022863aa4a29f5611fde02258f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 04:52:20 -0700 Subject: - use an environment variable and venv. See https://github.com/Pylons/pyramid/pull/2468#discussion_r59311019 - rename stanza from `testing_extras` to `tests_require` - switch from nose to pytest --- docs/narr/commandline.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 3e164ee8d..7f112550f 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -926,7 +926,7 @@ top-level directory, your ``setup.py`` file will look something like this: requires = ['pyramid', 'pyramid_debugtoolbar'] - testing_extras = [ + tests_require = [ 'WebTest >= 1.3.1', # py3 compat 'pytest', # includes virtualenv 'pytest-cov', @@ -951,7 +951,7 @@ top-level directory, your ``setup.py`` file will look something like this: zip_safe=False, install_requires=requires, extras_require={ - 'testing': testing_extras, + 'testing': tests_require, }, entry_points = """\ [paste.app_factory] @@ -993,7 +993,7 @@ The result will be something like: requires = ['pyramid', 'pyramid_debugtoolbar'] - testing_extras = [ + tests_require = [ 'WebTest >= 1.3.1', # py3 compat 'pytest', # includes virtualenv 'pytest-cov', @@ -1018,7 +1018,7 @@ The result will be something like: zip_safe=False, install_requires=requires, extras_require={ - 'testing': testing_extras, + 'testing': tests_require, }, entry_points = """\ [paste.app_factory] -- cgit v1.2.3 From d67566acebf890a603fad0e9069d5e131dfb5b31 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 06:43:38 -0700 Subject: one does not simply "create a virtualenv". one should "create a virtual environment". - Fixes #2483 --- docs/narr/commandline.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 7f112550f..6cd90d42f 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -815,17 +815,17 @@ Making Your Script into a Console Script ---------------------------------------- A "console script" is :term:`setuptools` terminology for a script that gets -installed into the ``bin`` directory of a Python :term:`virtualenv` (or "base" -Python environment) when a :term:`distribution` which houses that script is -installed. Because it's installed into the ``bin`` directory of a virtualenv -when the distribution is installed, it's a convenient way to package and -distribute functionality that you can call from the command-line. It's often -more convenient to create a console script than it is to create a ``.py`` -script and instruct people to call it with the "right" Python interpreter. A -console script generates a file that lives in ``bin``, and when it's invoked it -will always use the "right" Python environment, which means it will always be -invoked in an environment where all the libraries it needs (such as Pyramid) -are available. +installed into the ``bin`` directory of a Python :term:`virtual environment` +(or "base" Python environment) when a :term:`distribution` which houses that +script is installed. Because it's installed into the ``bin`` directory of a +virtual environment when the distribution is installed, it's a convenient way +to package and distribute functionality that you can call from the +command-line. It's often more convenient to create a console script than it is +to create a ``.py`` script and instruct people to call it with the "right" +Python interpreter. A console script generates a file that lives in ``bin``, +and when it's invoked it will always use the "right" Python environment, which +means it will always be invoked in an environment where all the libraries it +needs (such as Pyramid) are available. In general, you can make your script into a console script by doing the following: @@ -843,7 +843,7 @@ following: - Run ``pip install -e .`` or ``pip install .`` to get your distribution reinstalled. When you reinstall your distribution, a file representing the script that you named in the last step will be in the ``bin`` directory of - the virtualenv in which you installed the distribution. It will be + the virtual environment in which you installed the distribution. It will be executable. Invoking it from a terminal will execute your callable. As an example, let's create some code that can be invoked by a console script @@ -1029,7 +1029,7 @@ The result will be something like: ) Once you've done this, invoking ``$VENV/bin/pip install -e .`` will install a -file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a +file named ``show_settings`` into the ``$somevenv/bin`` directory with a small bit of Python code that points to your entry point. It will be executable. Running it without any arguments will print an error and exit. Running it with a single argument that is the path of a config file will print -- cgit v1.2.3