From 8109ae8ef7e04135a4724963951983ee260293a7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 13 Jan 2013 22:45:36 +0200 Subject: typo; should be 'titled', but would be redundant --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index ad22a82c9..7caea28b8 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article entitled `"A Whirlwind Rour of Advanced +For more information, see the article `"A Whirlwind Tour of Advanced Configuration Tactics" `_ in the Pyramid Cookbook. -- cgit v1.2.3 From b00f1e46f100d8a23041a1bb7a7b37b026170fe3 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 14 Jan 2013 08:50:51 -0500 Subject: Punctuate. --- docs/narr/advconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 7caea28b8..ba43f3ea6 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article `"A Whirlwind Tour of Advanced +For more information, see the article,`"A Whirlwind Tour of Advanced Configuration Tactics" -`_ +`_, in the Pyramid Cookbook. -- cgit v1.2.3 From fa1ac6744f1e2308190ba84dd60d573b4fa25fb3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 15 Jan 2013 00:56:42 +0200 Subject: another grammar fix --- docs/api/config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api/config.rst b/docs/api/config.rst index 5d2bce23e..e6a67830e 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -130,7 +130,7 @@ .. attribute:: global_registries The set of registries that have been created for :app:`Pyramid` - applications, one per each call to + applications, one for each call to :meth:`pyramid.config.Configurator.make_wsgi_app` in the current process. The object itself supports iteration and has a ``last`` property containing the last registry loaded. -- cgit v1.2.3 From 8e5b2d196a1d7825ecd59a39709ef0dbd2c134e1 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 16 Jan 2013 00:39:52 +0200 Subject: improve flow --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0b85d68d3..9aea50185 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -200,7 +200,7 @@ and various other configuration settings have been performed). The be used by any WSGI server to present an application to a requestor. :term:`WSGI` is a protocol that allows servers to talk to Python applications. We don't discuss :term:`WSGI` in any depth within this book, -however, you can learn more about it by visiting `wsgi.org +but you can learn more about it by visiting `wsgi.org `_. The :app:`Pyramid` application object, in particular, is an instance of a -- cgit v1.2.3 From 362d8b0548410e7ab3e28d0d420342121496a1d2 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 16 Jan 2013 00:44:45 +0200 Subject: improve flow --- docs/narr/firstapp.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0b85d68d3..45cb917f7 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -194,8 +194,8 @@ WSGI Application Creation After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` method. A call to ``make_wsgi_app`` implies that all configuration is -finished (meaning all method calls to the configurator which set up views, -and various other configuration settings have been performed). The +finished (meaning all method calls to the configurator, which sets up views +and various other configuration settings, have been performed). The ``make_wsgi_app`` method returns a :term:`WSGI` application object that can be used by any WSGI server to present an application to a requestor. :term:`WSGI` is a protocol that allows servers to talk to Python -- cgit v1.2.3 From 7e10cd0fd38bdeeba988e6ecf1b6179a0086559c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 17 Jan 2013 22:06:50 +0200 Subject: miscellaneous doc improvements * the word "system" can be misleading, so use a clearer choice of words * reduce repetition * mention Debian, since it is similar to Ubuntu, and is major enough * it is now "Ubuntu", not "Ubuntu Linux" --- docs/narr/install.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index a78c1b2bd..6653243d5 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -40,13 +40,11 @@ UNIX system that has development tools. Package Manager Method ++++++++++++++++++++++ -You can use your system's "package manager" to install Python. Every -system's package manager is slightly different, but the "flavor" of +You can use your system's "package manager" to install Python. +Each package manager is slightly different, but the "flavor" of them is usually the same. -For example, on an Ubuntu Linux system, to use the system package -manager to install a Python 2.7 interpreter, use the following -command: +For example, on a Debian or Ubuntu system, use the following command: .. code-block:: text -- cgit v1.2.3 From b31e5c9c46f4d87177b114f50328a8b0b39908be Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 17 Jan 2013 22:30:25 +0200 Subject: fix #747 --- docs/narr/install.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index a78c1b2bd..19c144156 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -70,7 +70,8 @@ Python interpreter to develop your software. The authors of :app:`Pyramid` tend not to use the system Python for development purposes; always a self-compiled one. Compiling Python is usually easy, and often the "system" Python is compiled with options that -aren't optimal for web development. +aren't optimal for web development. For an explanation, see +https://github.com/Pylons/pyramid/issues/747. To compile software on your UNIX system, typically you need development tools. Often these can be installed via the package -- cgit v1.2.3 From e241c7e479b411a7f465b0a3d86021301702f8af Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 18 Jan 2013 23:58:04 +0200 Subject: make example links clickable, for convenience --- docs/index.rst | 2 +- docs/narr/firstapp.rst | 2 +- docs/narr/urldispatch.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 0d6113c15..d4b7ed492 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ Here is one of the simplest :app:`Pyramid` applications you can make: .. literalinclude:: narr/helloworld.py After you install :app:`Pyramid` and run this application, when you visit -``http://localhost:8080/hello/world`` in a browser, you will see the text +``_ in a browser, you will see the text ``Hello, world!`` See :ref:`firstapp_chapter` for a full explanation of how this application diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0b85d68d3..50aa02692 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -40,7 +40,7 @@ On Windows: This command will not return and nothing will be printed to the console. When port 8080 is visited by a browser on the URL ``/hello/world``, the server will simply serve up the text "Hello world!". If your application is -running on your local system, using ``http://localhost:8080/hello/world`` +running on your local system, using ``_ in a browser will show this result. Each time you visit a URL served by the application in a browser, a logging diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 46f908b7c..ec97bf3b2 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -38,7 +38,7 @@ application. A route has a *name*, which acts as an identifier to be used for URL generation. The name also allows developers to associate a view configuration with the route. A route also has a *pattern*, meant to match against the ``PATH_INFO`` portion of a URL (the portion following the scheme -and port, e.g. ``/foo/bar`` in the URL ``http://localhost:8080/foo/bar``). It +and port, e.g. ``/foo/bar`` in the URL ``_). It also optionally has a ``factory`` and a set of :term:`route predicate` attributes. -- cgit v1.2.3 From 29492930e2b04a854371160ddae568ca76536f04 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 19 Jan 2013 11:01:56 +0200 Subject: missing comma --- docs/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 5b165db0a..0036d045b 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -689,7 +689,7 @@ Glossary non-C based Python implementations. View Lookup - The act of finding and invoking the "best" :term:`view callable` + The act of finding and invoking the "best" :term:`view callable`, given a :term:`request` and a :term:`context` resource. Resource Location -- cgit v1.2.3 From 445eb8708fa48209947377f6de609799dd843ad6 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 20 Jan 2013 17:10:40 +0200 Subject: point to the sources of the wiki tutorials in just one location; fix #763 * This avoids having to update the link multiple times. * Also, mention their location, in case user has Pyramid checkout. --- docs/tutorials/wiki/authorization.rst | 3 --- docs/tutorials/wiki/basiclayout.rst | 3 --- docs/tutorials/wiki/definingmodels.rst | 3 --- docs/tutorials/wiki/definingviews.rst | 3 --- docs/tutorials/wiki/index.rst | 5 +++-- docs/tutorials/wiki/tests.rst | 3 --- docs/tutorials/wiki2/authorization.rst | 3 --- docs/tutorials/wiki2/basiclayout.rst | 3 --- docs/tutorials/wiki2/definingmodels.rst | 3 --- docs/tutorials/wiki2/definingviews.rst | 3 --- docs/tutorials/wiki2/index.rst | 6 +++--- docs/tutorials/wiki2/tests.rst | 3 --- 12 files changed, 6 insertions(+), 35 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index e90dfe12d..7c8ba99bf 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -32,9 +32,6 @@ Then we will add the login and logout feature: * Add a "Logout" link to be shown when logged in and viewing or editing a page (``view.pt``, ``edit.pt``). -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/authorization/ -`_. Access Control -------------- diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index da381ad7b..aab22408b 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -6,9 +6,6 @@ The starter files generated by the ``zodb`` scaffold are basic, but they provide a good orientation for the high-level patterns common to most :term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects. -The source code for this tutorial stage can be browsed via -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/basiclayout/ -`_. Application Configuration with ``__init__.py`` ------------------------------------------------ diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst index 2cbe691fa..1d2710975 100644 --- a/docs/tutorials/wiki/definingmodels.rst +++ b/docs/tutorials/wiki/definingmodels.rst @@ -14,9 +14,6 @@ constructors". Both our Page and Wiki constructors will be class objects. A single instance of the "Wiki" class will serve as a container for "Page" objects, which will be instances of the "Page" class. -The source code for this tutorial stage can be browsed via -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/models/ -`_. Delete the Database ------------------- diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 27f55da13..efcc7bf21 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -28,9 +28,6 @@ assumed to return a :term:`response` object. We're going to define several :term:`view callable` functions, then wire them into :app:`Pyramid` using some :term:`view configuration`. -The source code for this tutorial stage can be browsed via -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/views/ -`_. Declaring Dependencies in Our ``setup.py`` File =============================================== diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst index c918f8765..981d135c7 100644 --- a/docs/tutorials/wiki/index.rst +++ b/docs/tutorials/wiki/index.rst @@ -10,8 +10,9 @@ tutorial, the developer will have created a basic Wiki application with authentication. For cut and paste purposes, the source code for all stages of this -tutorial can be browsed at `https://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src -`_. +tutorial can be browsed on GitHub at `docs/tutorials/wiki/src +`_, +which corresponds to the same location if you have Pyramid sources. .. toctree:: :maxdepth: 2 diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index 7a019dd04..49bc780e8 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -6,9 +6,6 @@ We will now add tests for the models and the views and a few functional tests in the ``tests.py``. Tests ensure that an application works, and that it continues to work after some changes are made in the future. -The source code for this tutorial stage can be browsed via -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/tests/ -`_. Test the Models =============== diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 321f1f9c4..5ede26920 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -36,9 +36,6 @@ Then we will add the login and logout feature: * Add a "Logout" link to be shown when logged in and viewing or editing a page (``view.pt``, ``edit.pt``). -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/authorization/ -`_. Access Control -------------- diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index e8874784c..68be4ee7c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -6,9 +6,6 @@ The starter files generated by the ``alchemy`` scaffold are very basic, but they provide a good orientation for the high-level patterns common to most :term:`url dispatch` -based :app:`Pyramid` projects. -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/basiclayout/ -`_. Application Configuration with ``__init__.py`` ---------------------------------------------- diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index dca6238dd..bd1cb00d7 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -6,9 +6,6 @@ The first change we'll make to our stock ``pcreate``-generated application will be to define a :term:`domain model` constructor representing a wiki page. We'll do this inside our ``models.py`` file. -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/models/ -`_. Making Edits to ``models.py`` ----------------------------- diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 8714927c3..e83a88198 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -16,9 +16,6 @@ instance, if a call to :meth:`pyramid.config.Configurator.add_route` in have a ``'one'`` key with the value ``'foo'`` and a ``'two'`` key with the value ``'bar'``. -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/views/ -`_. Declaring Dependencies in Our ``setup.py`` File =============================================== diff --git a/docs/tutorials/wiki2/index.rst b/docs/tutorials/wiki2/index.rst index bbc2fb96e..0a614cb23 100644 --- a/docs/tutorials/wiki2/index.rst +++ b/docs/tutorials/wiki2/index.rst @@ -9,9 +9,9 @@ tutorial is finished, the developer will have created a basic Wiki application with authentication. For cut and paste purposes, the source code for all stages of this -tutorial can be browsed at -`https://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src -`_. +tutorial can be browsed on GitHub at `docs/tutorials/wiki2/src +`_, +which corresponds to the same location if you have Pyramid sources. .. toctree:: :maxdepth: 2 diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index 6a7cbf62d..83df86b27 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -6,9 +6,6 @@ We will now add tests for the models and the views and a few functional tests in the ``tests.py``. Tests ensure that an application works, and that it continues to work after changes are made in the future. -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/tests/ -`_. Testing the Models -- cgit v1.2.3 From 1e7d75e55428127865cd8bf18576fd71bdf7e5ee Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 21 Jan 2013 00:03:25 +0200 Subject: fix typos --- docs/narr/renderers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index ecf625251..5379a4a99 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -823,8 +823,8 @@ sets an ``override_renderer`` attribute on the request itself, which is the .. code-block:: python :linenos: - from pyramid.event import subscriber - from pyramid.event import NewRequest + from pyramid.events import subscriber + from pyramid.events import NewRequest @subscriber(NewRequest) def set_xmlrpc_params(event): -- cgit v1.2.3 From c1b83b4ef365986e831530f62b3c1045aa524a07 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Jan 2013 02:02:22 -0800 Subject: etc. is an abbreviation --- docs/tutorials/wiki/background.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst index ac337abd5..6bbd5026e 100644 --- a/docs/tutorials/wiki/background.rst +++ b/docs/tutorials/wiki/background.rst @@ -11,7 +11,7 @@ Python web framework experience. To code along with this tutorial, the developer will need a UNIX machine with development tools (Mac OS X with XCode, any Linux or BSD -variant, etc) *or* a Windows system of any kind. +variant, etc.) *or* a Windows system of any kind. .. warning:: -- cgit v1.2.3 From 3ead59ea06ee933f4729f6b021d886be53f655be Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Jan 2013 02:21:18 -0800 Subject: minor grammar, spelling --- docs/tutorials/wiki/design.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index b44ccb10e..eb785dd1c 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -4,7 +4,7 @@ Design Following is a quick overview of our wiki application, to help us understand the changes that we will be doing next in our -default files generated by the ``zodb`` scafffold. +default files generated by the ``zodb`` scaffold. Overall ------- @@ -37,8 +37,8 @@ Views ----- There will be three views to handle the normal operations of adding, -editing and viewing wiki pages, plus one view for the wiki front page. -Two templates will be used, one for viewing, and one for both for adding +editing, and viewing wiki pages, plus one view for the wiki front page. +Two templates will be used, one for viewing, and one for both adding and editing wiki pages. The default templating systems in :app:`Pyramid` are @@ -57,7 +57,7 @@ use to do this are below. corresponding passwords. - GROUPS, a dictionary mapping usernames to a - list of groups they belong to. + list of groups to which they belong to. - ``groupfinder``, an *authorization callback* that looks up USERS and GROUPS. It will be provided in a new -- cgit v1.2.3 From e266bc346f161087037647084c92c4ad26de2739 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Jan 2013 04:05:24 -0800 Subject: Grammar: either "e.g.", or "etc.", but not both in the same phrase. --- docs/tutorials/wiki/installation.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 488ab1883..b545cdba0 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -193,8 +193,7 @@ assumptions: .. note:: - :app:`Pyramid` supports any persistent storage mechanism (e.g. a SQL - database or filesystem files, etc). :app:`Pyramid` also supports an - additional mechanism to map URLs to code (:term:`URL dispatch`). However, - for the purposes of this tutorial, we'll only be using traversal and ZODB. - + :app:`Pyramid` supports any persistent storage mechanism (e.g., a SQL + database or filesystem files). :app:`Pyramid` also supports an additional + mechanism to map URLs to code (:term:`URL dispatch`). However, for the + purposes of this tutorial, we'll only be using traversal and ZODB. -- cgit v1.2.3 From 2b126ef15ee7d8457592faea02f837cf2a6062d4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 22 Jan 2013 07:51:49 +0200 Subject: consistency fixes --- docs/narr/renderers.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 5379a4a99..794e3cffa 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -73,13 +73,13 @@ which renders view return values to a :term:`JSON` response serialization. Other built-in renderers include renderers which use the :term:`Chameleon` templating language to render a dictionary to a response. Additional -renderers can be added by developers to the system as necessary (see -:ref:`adding_and_overriding_renderers`). +renderers can be added by developers to the system as necessary. +See :ref:`adding_and_overriding_renderers`. Views which use a renderer and return a non-Response value can vary non-body response attributes (such as headers and the HTTP status code) by attaching a -property to the ``request.response`` attribute See -:ref:`request_response_attr`. +property to the ``request.response`` attribute. +See :ref:`request_response_attr`. If the :term:`view callable` associated with a :term:`view configuration` returns a Response object directly, any renderer associated with the view -- cgit v1.2.3 From 14ffa6c187e30c2756adc548f90c8ab6de34534c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 22 Jan 2013 08:07:31 +0200 Subject: typo --- docs/tutorials/wiki/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index aab22408b..756a4b3b5 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -165,7 +165,7 @@ opposed to the tutorial :term:`package` directory) looks like this: .. literalinclude:: src/basiclayout/development.ini :language: ini -Note the existence of an ``[app:main]`` section which specifies our WSGI +Note the existence of a ``[app:main]`` section which specifies our WSGI application. Our ZODB database settings are specified as the ``zodbconn.uri`` setting within this section. This value, and the other values within this section are passed as ``**settings`` to the ``main`` -- cgit v1.2.3 From 49d8235ccca2055ca368f751037136175f80d015 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 22 Jan 2013 00:06:20 -0800 Subject: More grammar clean up. --- docs/tutorials/wiki/basiclayout.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index aab22408b..03abedbd8 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -4,7 +4,7 @@ Basic Layout The starter files generated by the ``zodb`` scaffold are basic, but they provide a good orientation for the high-level patterns common to most -:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects. +:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` -based) projects. Application Configuration with ``__init__.py`` @@ -12,8 +12,8 @@ Application Configuration with ``__init__.py`` A directory on disk can be turned into a Python :term:`package` by containing an ``__init__.py`` file. Even if empty, this marks a directory as a Python -package. Our application uses ``__init__.py`` as both a package marker, as -well as to contain application configuration code. +package. Our application uses ``__init__.py`` both as a package marker and +to contain application configuration code. When you run the application using the ``pserve`` command using the ``development.ini`` generated config file, the application configuration @@ -28,14 +28,14 @@ point happens to be the ``main`` function within the file named #. *Lines 1-3*. Perform some dependency imports. -#. *Lines 6-8* Define a root factory for our Pyramid application. +#. *Lines 6-8*. Define a root factory for our Pyramid application. #. *Line 14*. We construct a :term:`Configurator` with a :term:`root factory` and the settings keywords parsed by :term:`PasteDeploy`. The root factory is named ``root_factory``. -#. *Line 15*. Register a 'static view' which answers requests which start - with URL path ``/static`` using the +#. *Line 15*. Register a "static view" which answers requests whose URL path + start with ``/static`` using the :meth:`pyramid.config.Configurator.add_static_view method`. This statement registers a view that will serve up static assets, such as CSS and image files, for us, in this case, at @@ -44,16 +44,16 @@ point happens to be the ``main`` function within the file named will be ``/static``. The second argument of this tag is the "path", which is a relative :term:`asset specification`, so it finds the resources it should serve within the ``static`` directory inside the ``tutorial`` - package. The scaffold could have alternately used an *absolute* asset - specification as the path (``tutorial:static``) but it does not. + package. Alternatively the scaffold could have used an *absolute* asset + specification as the path (``tutorial:static``). #. *Line 16*. Perform a :term:`scan`. A scan will find :term:`configuration - decoration`, such as view configuration decorators (e.g. ``@view_config``) + decoration`, such as view configuration decorators (e.g., ``@view_config``) in the source code of the ``tutorial`` package and will take actions based on these decorators. We don't pass any arguments to :meth:`~pyramid.config.Configurator.scan`, which implies that the scan should take place in the current package (in this case, ``tutorial``). - The scaffold could have equivalently said ``config.scan('tutorial')`` but + The scaffold could have equivalently said ``config.scan('tutorial')``, but it chose to omit the package name argument. #. *Line 17*. Use the @@ -70,7 +70,7 @@ tree represents the site structure, but it *also* represents the :term:`domain model` of the application, because each resource is a node stored persistently in a :term:`ZODB` database. The ``models.py`` file is where the ``zodb`` scaffold put the classes that implement our -resource objects, each of which happens also to be a domain model object. +resource objects, each of which also happens to be a domain model object. Here is the source for ``models.py``: @@ -79,7 +79,7 @@ Here is the source for ``models.py``: :language: py #. *Lines 4-5*. The ``MyModel`` :term:`resource` class is implemented here. - Instances of this class will be capable of being persisted in :term:`ZODB` + Instances of this class are capable of being persisted in :term:`ZODB` because the class inherits from the :class:`persistent.mapping.PersistentMapping` class. The ``__parent__`` and ``__name__`` are important parts of the :term:`traversal` protocol. @@ -137,7 +137,7 @@ Let's try to understand the components in this module: indeed if you look in the ``templates`` directory of this package, you'll see a ``mytemplate.pt`` template file, which renders the default home page of the generated project. This asset specification is *relative* (to the - view.py's current package). We could have alternately an used the + view.py's current package). Alternatively we could have used the absolute asset specification ``tutorial:templates/mytemplate.pt``, but chose to use the relative version. -- cgit v1.2.3 From f1134866e8ca96e1309dca930bd5345233748659 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 22 Jan 2013 00:16:17 -0800 Subject: More grammar clean up. --- docs/tutorials/wiki/definingmodels.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst index 1d2710975..49372179f 100644 --- a/docs/tutorials/wiki/definingmodels.rst +++ b/docs/tutorials/wiki/definingmodels.rst @@ -33,7 +33,7 @@ Edit ``models.py`` .. note:: There is nothing automagically special about the filename ``models.py``. A - project may have many models throughout its codebase in arbitrarily-named + project may have many models throughout its codebase in arbitrarily named files. Files implementing models often have ``model`` in their filenames, or they may live in a Python subpackage of your application package named ``models``, but this is only by convention. @@ -56,7 +56,7 @@ of the root model is also always ``None``. Then we'll add a ``Page`` class. This class should inherit from the :class:`persistent.Persistent` class. We'll also give it an ``__init__`` method that accepts a single parameter named ``data``. This parameter will -contain the :term:`ReStructuredText` body representing the wiki page content. +contain the :term:`reStructuredText` body representing the wiki page content. Note that ``Page`` objects don't have an initial ``__name__`` or ``__parent__`` attribute. All objects in a traversal graph must have a ``__name__`` and a ``__parent__`` attribute. We don't specify these here -- cgit v1.2.3 From 0b23b34cf7f759d7f2895696b8ec07c3a4d1e80a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 23 Jan 2013 01:43:48 +0200 Subject: pyramid.config: take advantage of some Sphinx directives * versionadded * versionchanged * deprecated --- docs/api/config.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/api/config.rst b/docs/api/config.rst index e6a67830e..39d504348 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -108,9 +108,7 @@ :class:`pyramid.registry.Introspectable` class (used during directives to provide introspection to actions). - .. note:: - - This attribute is new as of :app:`Pyramid` 1.3. + .. versionadded:: 1.3 .. attribute:: introspector @@ -118,9 +116,7 @@ instance implementing the :class:`pyramid.interfaces.IIntrospector` interface. - .. note:: - - This attribute is new as of :app:`Pyramid` 1.3. + .. versionadded:: 1.3 .. attribute:: registry -- cgit v1.2.3 From b515ddcf759ebe267b9ee74a1d5af72da8639ae0 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 23 Jan 2013 21:56:28 +0200 Subject: displaying line numbers for 1-line snippets is overkill --- docs/narr/renderers.rst | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 794e3cffa..5391a6669 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -63,7 +63,6 @@ the ``renderer`` attribute. For example, this call to with a view callable: .. code-block:: python - :linenos: config.add_view('myproject.views.my_view', renderer='json') @@ -166,7 +165,6 @@ The body of the response returned by such a view will be a string representing the ``str()`` serialization of the return value: .. code-block:: python - :linenos: {'content': 'Hello!'} @@ -204,7 +202,6 @@ The body of the response returned by such a view will be a string representing the JSON serialization of the return value: .. code-block:: python - :linenos: '{"content": "Hello!"}' @@ -619,7 +616,6 @@ For example, to add a renderer which renders views which have a ``renderer`` attribute that is a path that ends in ``.jinja2``: .. code-block:: python - :linenos: config.add_renderer('.jinja2', 'mypackage.MyJinja2Renderer') @@ -725,10 +721,8 @@ Here's an example of the registration of a more complicated renderer factory, which expects to be passed a filesystem path: .. code-block:: python - :linenos: - config.add_renderer(name='.jinja2', - factory='my.package.MyJinja2Renderer') + config.add_renderer(name='.jinja2', factory='my.package.MyJinja2Renderer') Adding the above code to your application startup will allow you to use the ``my.package.MyJinja2Renderer`` renderer factory implementation in view @@ -769,7 +763,6 @@ extension for the same kinds of templates. For example, to associate the :meth:`pyramid.config.Configurator.add_renderer` method: .. code-block:: python - :linenos: config.add_renderer('.zpt', 'pyramid.chameleon_zpt.renderer_factory') @@ -781,7 +774,6 @@ rendered via a Chameleon ZPT page template renderer, use a variation on the following in your application's startup code: .. code-block:: python - :linenos: config.add_renderer('.pt', 'mypackage.pt_renderer') @@ -794,7 +786,6 @@ ones which do not possess a ``renderer`` attribute), pass ``None`` as the ``name`` attribute to the renderer tag: .. code-block:: python - :linenos: config.add_renderer(None, 'mypackage.json_renderer_factory') -- cgit v1.2.3 From 5ed0d3df82787f95338a0dffa8c6a56efb28c6ee Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 23 Jan 2013 21:59:46 +0200 Subject: use 'versionadded' Sphinx directive --- docs/narr/renderers.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 5391a6669..deb0f6ee8 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -291,9 +291,8 @@ with the object. See :class:`pyramid.renderers.JSON` and :ref:`adding_and_overriding_renderers` for more information. -.. note:: - - Serializing custom objects is a feature new in Pyramid 1.4. +.. versionadded:: 1.4 + Serializing custom objects. .. index:: pair: renderer; JSONP @@ -303,9 +302,7 @@ See :class:`pyramid.renderers.JSON` and JSONP Renderer ~~~~~~~~~~~~~~ -.. note:: - - This feature is new in Pyramid 1.1. +.. versionadded:: 1.1 :class:`pyramid.renderers.JSONP` is a `JSONP `_ renderer factory helper which -- cgit v1.2.3 From 2947141248946db191843c5bc1629c60e7ad8f3a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 23 Jan 2013 22:00:10 +0200 Subject: user 'deprecated' Sphinx directive --- docs/narr/renderers.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index deb0f6ee8..b7d3479dc 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -565,7 +565,8 @@ in :ref:`request_module`. For more information on the API of Deprecated Mechanism to Vary Attributes of Rendered Responses ------------------------------------------------------------- -.. warning:: This section describes behavior deprecated in Pyramid 1.1. +.. deprecated:: 1.1 + The behavior described in this entire section. In previous releases of Pyramid (1.0 and before), the ``request.response`` attribute did not exist. Instead, Pyramid required users to set special -- cgit v1.2.3 From 531a2ad34ab0a806513681cddd5d99e50a31c4c6 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 23 Jan 2013 22:01:56 +0200 Subject: provide a link to the class; lineno for a 1-liner is overkill --- docs/narr/renderers.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index b7d3479dc..863932e83 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -683,12 +683,10 @@ There are essentially two different kinds of renderer factories: :term:`package`. Here's an example of the registration of a simple renderer factory via -:meth:`~pyramid.config.Configurator.add_renderer`: +:meth:`~pyramid.config.Configurator.add_renderer`, where ``config`` +is an instance of :meth:`pyramid.config.Configurator`: .. code-block:: python - :linenos: - - # config is an instance of pyramid.config.Configurator config.add_renderer(name='amf', factory='my.package.MyAMFRenderer') -- cgit v1.2.3 From f564808a72d2720888525f6684dc79cc2affb6e9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 24 Jan 2013 00:56:50 -0800 Subject: Add source code snippets to supply context for the narrative. --- docs/tutorials/wiki/definingviews.rst | 37 ++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index efcc7bf21..4dedf4320 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -71,6 +71,13 @@ and a final view named ``edit_page`` will allow a page to be edited. The ``view_wiki`` view function ------------------------------- +Here is the code for the ``view_wiki`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 12-14 + :language: python + The ``view_wiki`` function will be configured to respond as the default view callable for a Wiki resource. We'll provide it with a ``@view_config`` decorator which names the class ``tutorial.models.Wiki`` as its context. @@ -84,16 +91,22 @@ The ``view_wiki`` view callable always redirects to the URL of a Page resource named "FrontPage". To do so, it returns an instance of the :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement the :class:`pyramid.interfaces.IResponse` interface like -:class:`pyramid.response.Response` does). The -:meth:`pyramid.request.Request.resource_url` API. +:class:`pyramid.response.Response` does). :meth:`pyramid.request.Request.resource_url` constructs a URL to the -``FrontPage`` page resource (e.g. ``http://localhost:6543/FrontPage``), and +``FrontPage`` page resource (i.e., ``http://localhost:6543/FrontPage``), and uses it as the "location" of the HTTPFound response, forming an HTTP redirect. The ``view_page`` view function ------------------------------- +Here is the code for the ``view_page`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 16-33 + :language: python + The ``view_page`` function will be configured to respond as the default view of a Page resource. We'll provide it with a ``@view_config`` decorator which names the class ``tutorial.models.Page`` as its context. This means that @@ -101,7 +114,7 @@ when a Page resource is the context, and no :term:`view name` exists in the request, this view will be used. We inform :app:`Pyramid` this view will use the ``templates/view.pt`` template file as a ``renderer``. -The ``view_page`` function generates the :term:`ReStructuredText` body of a +The ``view_page`` function generates the :term:`reStructuredText` body of a page (stored as the ``data`` attribute of the context passed to the view; the context will be a Page resource) as HTML. Then it substitutes an HTML anchor for each *WikiWord* reference in the rendered HTML using a compiled regular @@ -140,6 +153,13 @@ callable. In the ``view_wiki`` view callable, we unconditionally return a The ``add_page`` view function ------------------------------ +Here is the code for the ``add_page`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 35-50 + :language: python + The ``add_page`` function will be configured to respond when the context resource is a Wiki and the :term:`view name` is ``add_page``. We'll provide it with a ``@view_config`` decorator which names the string ``add_page`` as @@ -171,7 +191,7 @@ we're trying to add. If the view rendering is *not* a result of a form submission (if the expression ``'form.submitted' in request.params`` is ``False``), the view renders a template. To do so, it generates a "save url" which the template -use as the form post URL during rendering. We're lazy here, so we're trying +uses as the form post URL during rendering. We're lazy here, so we're trying to use the same template (``templates/edit.pt``) for the add view as well as the page edit view. To do so, we create a dummy Page resource object in order to satisfy the edit form's desire to have *some* page object exposed as @@ -187,6 +207,13 @@ the page body, and save it into "our context" (the Wiki) using the The ``edit_page`` view function ------------------------------- +Here is the code for the ``edit_page`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 52-60 + :language: python + The ``edit_page`` function will be configured to respond when the context is a Page resource and the :term:`view name` is ``edit_page``. We'll provide it with a ``@view_config`` decorator which names the string ``edit_page`` as its -- cgit v1.2.3 From fdcd1beef58e106b556f6586f4a95e02d6aec1f4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 28 Jan 2013 08:27:05 +0200 Subject: use a more correct directive --- docs/narr/environment.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 8206e0bcb..def5e12a4 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -504,12 +504,13 @@ default, this is ``false``. Mako Preprocessor ~~~~~~~~~~~~~~~~~ +.. versionadded:: 1.1 + A callable (or a :term:`dotted Python name` which names a callable) which is called to preprocess the source before the template is called. The callable will be passed the full template source before it is parsed. The return result of the callable will be used as the template source code. -.. note:: This feature is new in Pyramid 1.1. +-----------------------------+ | Config File Setting Name | -- cgit v1.2.3 From 9db1a14cd16f6e92fdb72650d2a3e3ef6e55ef9a Mon Sep 17 00:00:00 2001 From: kusut Date: Mon, 28 Jan 2013 23:42:27 +0700 Subject: narrative docs for add_request_method --- docs/narr/hooks.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b5efc0df1..957426ec2 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -256,6 +256,97 @@ already constructed a :term:`configurator` it can also be registered via the config = Configurator() config.set_request_factory(MyRequest) +.. index:: + single: request method + +.. _adding_request_method: + +Adding Methods or Properties to Request Object +---------------------------------------------- + +Since each pyramid application can only have one :term:`request` factory, +:ref:`changing the request factory ` +is not that extensible especially if you want to build composable features +(e.g., pyramid add-ons and plugins). + +A lazy property can be registered to the request object via the +:meth:`pyramid.config.Configurator.add_request_method` API. This allows you +to specify a callable that will be available on the request object, but will not +actually execute the function until accessed. + +.. note:: This feature is new as of Pyramid 1.4. + +.. warning:: This will silently override methods and properties from + :term:`request factory` that have the same name. + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + def total(request, *args): + return sum(args) + + def prop(request): + print "getting the property" + return "the property" + + config = Configurator() + config.add_request_method(total) + config.add_request_method(prop, reify=True) + +In the above example, ``total`` is added as a method. However, ``prop`` is added +as a property and its result is cached per-request by setting ``reify=True``. +This way, we eliminate the overhead of running the function multiple times. + + >>> request.total(1, 2, 3) + 6 + >>> request.prop + getting the property + the property + >>> request.prop + the property + +To not cache the result of ``request.prop``, set ``property=True`` instead of +``reify=True``. + +Here is an example of passing a class to ``Configurator.add_request_method``: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + from pyramid.decorator import reify + + + class ExtraStuff(object): + + def __init__(self, request): + self.request = request + + def total(self, *args): + return sum(args) + + # use @property if you don't want to cache the result + @reify + def prop(self): + print "getting the property" + return "the property" + + config = Configurator() + config.add_request_method(ExtraStuff, 'extra', reify=True) + +We attach and cache an object named ``extra`` to the ``request`` object. + + >>> request.extra.total(1, 2, 3) + 6 + >>> request.extra.prop + getting the property + the property + >>> request.extra.prop + the property + + .. index:: single: before render event single: adding renderer globals -- cgit v1.2.3 From 1c0e0e94b6665ba715236be82cbd2b12b6a0a79f Mon Sep 17 00:00:00 2001 From: Calvin Hendryx-Parker Date: Mon, 28 Jan 2013 17:08:21 -0500 Subject: Update docs/narr/extending.rst Fixed grammatical typo --- docs/narr/extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index c464203f0..dd9281c73 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -84,7 +84,7 @@ function in your application's ``__init__.py``. For example, rather than: config.add_view('myapp.views.view1', name='view1') config.add_view('myapp.views.view2', name='view2') -You should do move the calls to ``add_view`` outside of the (non-reusable) +You should move the calls to ``add_view`` outside of the (non-reusable) ``if __name__ == '__main__'`` block, and into a reusable function: .. code-block:: python -- cgit v1.2.3 From 0a9a29e9391e9b8639de61473bbe4865a6b0551e Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 29 Jan 2013 00:16:29 +0200 Subject: pluralize --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index f7da7838e..fa4affd8a 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -29,7 +29,7 @@ during your :app:`Pyramid` configuration. A very basic, insecure sample session factory implementation is provided in the :app:`Pyramid` core. It uses a cookie to store session information. This implementation has the following -limitation: +limitations: - The session information in the cookies used by this implementation is *not* encrypted, so it can be viewed by anyone with access to the -- cgit v1.2.3 From 479447a1ebc231096155290f918f563b884a3432 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 29 Jan 2013 01:03:37 +0200 Subject: replace 'note' with the more correct 'versionadded' directive --- docs/narr/urldispatch.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index ec97bf3b2..749a2d49a 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -758,11 +758,8 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. -.. note:: - - the ``static`` argument to - :meth:`~pyramid.config.Configurator.add_route` is new as of :app:`Pyramid` - 1.1. +.. versionadded:: 1.1 + the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` .. index:: single: redirecting to slash-appended routes @@ -906,7 +903,7 @@ routes configured in your application; for more information, see Using a Route Prefix to Compose Applications -------------------------------------------- -.. note:: This feature is new as of :app:`Pyramid` 1.2. +.. versionadded:: 1.2 The :meth:`pyramid.config.Configurator.include` method allows configuration statements to be included from separate files. See -- cgit v1.2.3 From 23c8985a661b9e2b11b76750893724dc747ffc1c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 29 Jan 2013 01:23:02 +0200 Subject: replace 'note' with the more correct 'versionadded' directive --- docs/api/request.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/api/request.rst b/docs/api/request.rst index e4034c635..9f1f71b31 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -163,9 +163,7 @@ .. method:: invoke_subrequest(request, use_tweens=False) - .. warning:: - - This API was added in Pyramid 1.4a1. + .. versionadded:: 1.4a1 Obtain a response object from the Pyramid application based on information in the ``request`` object provided. The ``request`` object -- cgit v1.2.3 From 5b9c21ebe7d295bb9ac4356033899181ac69396e Mon Sep 17 00:00:00 2001 From: kusut Date: Tue, 29 Jan 2013 22:16:00 +0700 Subject: enhance! --- docs/narr/hooks.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 957426ec2..d693149e4 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -264,18 +264,18 @@ already constructed a :term:`configurator` it can also be registered via the Adding Methods or Properties to Request Object ---------------------------------------------- -Since each pyramid application can only have one :term:`request` factory, +.. versionadded:: 1.4. + +Since each Pyramid application can only have one :term:`request` factory, :ref:`changing the request factory ` -is not that extensible especially if you want to build composable features -(e.g., pyramid add-ons and plugins). +is not that extensible, especially if you want to build composable features +(e.g., Pyramid add-ons and plugins). A lazy property can be registered to the request object via the :meth:`pyramid.config.Configurator.add_request_method` API. This allows you to specify a callable that will be available on the request object, but will not actually execute the function until accessed. -.. note:: This feature is new as of Pyramid 1.4. - .. warning:: This will silently override methods and properties from :term:`request factory` that have the same name. @@ -318,7 +318,6 @@ Here is an example of passing a class to ``Configurator.add_request_method``: from pyramid.config import Configurator from pyramid.decorator import reify - class ExtraStuff(object): def __init__(self, request): @@ -346,7 +345,6 @@ We attach and cache an object named ``extra`` to the ``request`` object. >>> request.extra.prop the property - .. index:: single: before render event single: adding renderer globals -- 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/api/registry.rst | 17 +++++++---------- docs/designdefense.rst | 2 +- docs/narr/commandline.rst | 3 ++- docs/narr/extconfig.rst | 4 +--- docs/narr/hooks.rst | 19 ++++++++----------- docs/narr/templates.rst | 8 ++------ docs/narr/viewconfig.rst | 8 +++----- docs/narr/views.rst | 4 ++-- docs/narr/webob.rst | 2 +- 9 files changed, 27 insertions(+), 40 deletions(-) (limited to 'docs') diff --git a/docs/api/registry.rst b/docs/api/registry.rst index a7879d3d5..db348495c 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -16,6 +16,8 @@ .. attribute:: introspector + .. versionadded:: 1.3 + When a registry is set up (or created) by a :term:`Configurator`, the registry will be decorated with an instance named ``introspector`` implementing the :class:`pyramid.interfaces.IIntrospector` interface. @@ -27,28 +29,23 @@ This attribute is often accessed as ``request.registry.introspector`` in a typical Pyramid application. - This attribute is new as of :app:`Pyramid` 1.3. - .. class:: Introspectable + .. versionadded:: 1.3 + The default implementation of the interface :class:`pyramid.interfaces.IIntrospectable` used by framework exenders. An instance of this class is created when :attr:`pyramid.config.Configurator.introspectable` is called. - This class is new as of :app:`Pyramid` 1.3. - .. autoclass:: Deferred - This class is new as of :app:`Pyramid` 1.4. + .. versionadded:: 1.4 .. autofunction:: undefer - This function is new as of :app:`Pyramid` 1.4. + .. versionadded:: 1.4 .. autoclass:: predvalseq - This class is new as of :app:`Pyramid` 1.4. - - - + .. versionadded:: 1.4 diff --git a/docs/designdefense.rst b/docs/designdefense.rst index f51ef10a9..69a921498 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -919,7 +919,7 @@ creating a more Zope3-like environment without much effort. Pyramid Uses its Own HTTP Exception Class Hierarchy Rather Than ``webob.exc`` ----------------------------------------------------------------------------- -.. note:: This defense is new as of Pyramid 1.1. +.. versionadded:: 1.1 The HTTP exception classes defined in :mod:`pyramid.httpexceptions` are very much like the ones defined in ``webob.exc`` 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 diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index 875bc9006..f33326279 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -227,9 +227,7 @@ augment Pyramid's configuration introspection system. Adding Configuration Introspection ---------------------------------- -.. note:: - - The introspection subsystem is new in Pyramid 1.3. +.. versionadded:: 1.3 Pyramid provides a configuration introspection system that can be used by debugging tools to provide visibility into the configuration of a running diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b5efc0df1..fc5c0ff23 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -336,9 +336,9 @@ when adding renderer global values exists in :ref:`adding_renderer_globals`. Adding Renderer Globals (Deprecated) ------------------------------------ -.. warning:: this feature is deprecated as of Pyramid 1.1. A non-deprecated - mechanism which allows event subscribers to add renderer global values - is documented in :ref:`beforerender_event`. +.. deprecated:: 1.1 + An alternative mechanism which allows event subscribers to add renderer + global values is documented in :ref:`beforerender_event`. Whenever :app:`Pyramid` handles a request to perform a rendering (after a view with a ``renderer=`` configuration attribute is invoked, or when any of @@ -635,13 +635,13 @@ See :meth:`pyramid.config.add_resource_url_adapter` for more information. Changing How Pyramid Treats View Responses ------------------------------------------ +.. versionadded:: 1.1 + It is possible to control how Pyramid treats the result of calling a view callable on a per-type basis by using a hook involving :meth:`pyramid.config.Configurator.add_response_adapter` or the :class:`~pyramid.response.response_adapter` decorator. -.. note:: This feature is new as of Pyramid 1.1. - Pyramid, in various places, adapts the result of calling a view callable to the :class:`~pyramid.interfaces.IResponse` interface to ensure that the object returned by the view callable is a "true" response object. The vast @@ -936,8 +936,8 @@ For full details, please read the `Venusian documentation Registering "Tweens" -------------------- -.. note:: Tweens are a feature which were added in Pyramid 1.2. They are - not available in any previous version. +.. versionadded:: 1.2 + Tweens A :term:`tween` (a contraction of the word "between") is a bit of code that sits between the Pyramid router's main request handling function and the @@ -1241,10 +1241,7 @@ implict and explicit tween chains used by an application. See Adding A Third Party View, Route, or Subscriber Predicate --------------------------------------------------------- -.. note:: - - Third-party view, route, and subscriber predicates are a feature new as of - Pyramid 1.4. +.. versionadded:: 1.4 .. _view_and_route_predicates: diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 1cec26fbc..6a1fbf916 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -543,9 +543,7 @@ template as a :term:`renderer` like so: The above will render only the ``bar`` macro defined within the ``foo.pt`` template instead of the entire template. -.. note:: - - This feature is new in Pyramid 1.4. +.. versionadded:: 1.4 .. index:: single: Chameleon text templates @@ -743,9 +741,7 @@ configure the template as a :term:`renderer` like so: The above will render the ``bar`` def from within the ``foo.mak`` template instead of the entire template. -.. note:: - - This feature is new in Pyramid 1.4. +.. versionadded:: 1.4 .. index:: single: automatic reloading of templates diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index f00dae451..7001cd980 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -306,7 +306,7 @@ configured view. consideration of keys and values in the ``request.params`` dictionary. ``match_param`` - .. note:: This feature is new as of :app:`Pyramid` 1.2. + .. versionadded:: 1.2 This param may be either a single string of the format "key=value" or a dict of key/value pairs. @@ -724,9 +724,7 @@ configuration to take effect. ``@view_defaults`` Class Decorator ---------------------------------- -.. note:: - - This feature is new in Pyramid 1.3. +.. versionadded:: 1.3 If you use a class as a view, you can use the :class:`pyramid.view.view_defaults` class decorator on the class to provide @@ -952,7 +950,7 @@ for more information about how, and where to set these values. Influencing HTTP Caching ------------------------ -.. note:: This feature is new in Pyramid 1.1. +.. versionadded:: 1.1 When a non-``None`` ``http_cache`` argument is passed to a view configuration, Pyramid will set ``Expires`` and ``Cache-Control`` response diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 4f30bb7fa..860c380f3 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -227,8 +227,8 @@ equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each HTTP response code to its purpose and its associated HTTP exception object is provided within :mod:`pyramid.httpexceptions`. -.. note:: The :func:`~pyramid.httpexceptions.exception_response` function is - new as of Pyramid 1.1. +.. versionadded:: 1.1 + The :func:`~pyramid.httpexceptions.exception_response` function. How Pyramid Uses HTTP Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index a8c11acec..44940f9e6 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -251,7 +251,7 @@ API documentation for a multidict exists as Dealing With A JSON-Encoded Request Body ++++++++++++++++++++++++++++++++++++++++ -.. note:: this feature is new as of Pyramid 1.1. +.. versionadded:: 1.1 :attr:`pyramid.request.Request.json_body` is a property that returns a :term:`JSON` -decoded representation of the request body. If the request -- cgit v1.2.3 From 6821582d7e691b8c068ce80ec067319c65195716 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 30 Jan 2013 01:18:06 +0200 Subject: this obsolete info should have been removed in commit 22ed77d --- docs/narr/install.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 224a62db7..c467779f4 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -166,9 +166,7 @@ distribute is not yet installed: ImportError: No module named setuptools If ``import setuptools`` raises an :exc:`ImportError` as it does above, you -will need to install setuptools or distribute manually. Note that above -we're using a Python 2.7-series interpreter on Mac OS X; your output may -differ if you're using a later Python version or a different platform. +will need to install setuptools or distribute manually. If you are using a "system" Python (one installed by your OS distributor or a 3rd-party packager such as Fink or MacPorts), you can usually install the -- cgit v1.2.3 From 3e9b1e566891bce88d63c188b92e223cb22dac2c Mon Sep 17 00:00:00 2001 From: Anton Vlasenko Date: Wed, 30 Jan 2013 22:58:18 +0200 Subject: Updated gunicorn information --- docs/glossary.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 0036d045b..9220e6b5f 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1015,8 +1015,7 @@ Glossary Green Unicorn Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under - Python 2.5+ (although at the time of this writing does not support - Python 3). See http://gunicorn.org/ for detailed information. + Python 2.6+ or Python 3.1+. See http://gunicorn.org/ for detailed information. predicate factory A callable which is used by a third party during the registration of a -- cgit v1.2.3 From 4d059a786bc019673715754be58fd61dd8d5359c Mon Sep 17 00:00:00 2001 From: "David\\ Beitey" Date: Thu, 31 Jan 2013 13:27:38 +1000 Subject: Document PredicateMismatch for exception contexts --- docs/api/exceptions.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst index 1dfbf46fd..ab158f18d 100644 --- a/docs/api/exceptions.rst +++ b/docs/api/exceptions.rst @@ -5,6 +5,8 @@ .. automodule:: pyramid.exceptions + .. autoclass:: PredicateMismatch + .. autoclass:: Forbidden .. autoclass:: NotFound -- cgit v1.2.3 From 3a6bdf983b51d8d0df124999ae217084c7dddbc6 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 3 Feb 2013 12:38:55 +0200 Subject: use clearer language --- docs/narr/environment.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index def5e12a4..281bb6919 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -203,7 +203,7 @@ Using the setting is equivalent to using the | | +---------------------------------+ -The value supplied as ``pyramid.includes`` should be a sequence. The +The value assigned to ``pyramid.includes`` should be a sequence. The sequence can take several different forms. 1) It can be a string. @@ -323,7 +323,7 @@ the behest of an add-on author. | | +---------------------------------+ -The value supplied as ``pyramid.tweens`` should be a sequence. The +The value assigned to ``pyramid.tweens`` should be a sequence. The sequence can take several different forms. 1) It can be a string. -- cgit v1.2.3 From 01c184719d026b8c61267e55b0646da9b86bd6a0 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 3 Feb 2013 23:44:51 +0200 Subject: remove questionable sentence I could not tell whether it was meant to be humorous, or if it simply was a mistake. Regardless, I think it does not add much. If Speed needs to be defended, perhaps something better would do. For now, I remove. --- docs/narr/introduction.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index c4f2ea512..809732220 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -52,9 +52,7 @@ Documentation Speed :app:`Pyramid` is designed to provide noticeably fast execution for common - tasks such as templating and simple response generation. Although "hardware - is cheap", the limits of this approach become painfully evident when one - finds him or herself responsible for managing a great many machines. + tasks such as templating and simple response generation. Reliability :app:`Pyramid` is developed conservatively and tested exhaustively. Where -- cgit v1.2.3 From 1d3b11ea4c7ce0e05ca80063f997596791f75fda Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 4 Feb 2013 20:53:03 +0200 Subject: fix and shorten broken sentence --- docs/narr/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index c4f2ea512..3540ee5c4 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -749,7 +749,7 @@ that we change Pyramid? You can extend Pyramid's :term:`Configurator` with your own directives. For example, let's say you find yourself calling :meth:`pyramid.config.Configurator.add_view` repetitively. Usually you can take the boring away by using existing shortcuts, but let's say that this is -a case such a way that no existing shortcut works to take the boring away: +a case where there is no such shortcut: .. code-block:: python :linenos: -- cgit v1.2.3 From bd070e77f4183a34507fe6f19604751cb78e3e8c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 4 Feb 2013 21:15:08 +0200 Subject: unuglify Unix Python installation instructions --- docs/narr/install.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index c467779f4..e18716baa 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -88,17 +88,15 @@ using the following commands: .. code-block:: text - [chrism@vitaminf ~]$ cd ~ - [chrism@vitaminf ~]$ mkdir tmp - [chrism@vitaminf ~]$ mkdir opt - [chrism@vitaminf ~]$ cd tmp - [chrism@vitaminf tmp]$ wget \ - http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz - [chrism@vitaminf tmp]$ tar xvzf Python-2.7.3.tgz - [chrism@vitaminf tmp]$ cd Python-2.7.3 - [chrism@vitaminf Python-2.7.3]$ ./configure \ - --prefix=$HOME/opt/Python-2.7.3 - [chrism@vitaminf Python-2.7.3]$ make; make install + $ cd ~ + $ mkdir tmp + $ mkdir opt + $ cd tmp + $ wget http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz + $ tar xvzf Python-2.7.3.tgz + $ cd Python-2.7.3 + $ ./configure --prefix=$HOME/opt/Python-2.7.3 + $ make && make install Once these steps are performed, the Python interpreter will be invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell -- cgit v1.2.3 From 148c7da017ef775932b2a4baeb0bd3057976adcc Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 4 Feb 2013 21:27:03 +0200 Subject: no need to be so specific This should reduce the frequency of needing to update it. --- docs/narr/install.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index c467779f4..91e1cae6f 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -14,8 +14,8 @@ run :app:`Pyramid`. .. sidebar:: Python Versions - As of this writing, :app:`Pyramid` has been tested under Python 2.6.8, - Python 2.7.3, Python 3.2.3, and Python 3.3b1. :app:`Pyramid` does not + As of this writing, :app:`Pyramid` has been tested under Python 2.6, + Python 2.7, Python 3.2, and Python 3.3. :app:`Pyramid` does not run under any version of Python before 2.6. :app:`Pyramid` is known to run on all popular UNIX-like systems such as -- cgit v1.2.3 From 37da2cf374792b2ab12ae39be6994540c9dfe623 Mon Sep 17 00:00:00 2001 From: Marc Abramowitz Date: Mon, 4 Feb 2013 15:23:46 -0800 Subject: narr/project.rst: Correct IP address 129.168.1.50 -> 192.168.1.50 --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fb62f4bd2..5a8ea0ecf 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -297,7 +297,7 @@ For example, your system might be configured to have an external IP address ``192.168.1.50``. If that's the case, if you use a browser running on the same system as Pyramid, it will be able to access the application via ``http://127.0.0.1:6543/`` as well as via -``http://129.168.1.50:6543/``. However, *other people* on other computers on +``http://192.168.1.50:6543/``. However, *other people* on other computers on the same network will also be able to visit your Pyramid application in their browser by visiting ``http://192.168.1.50:6543/``. -- cgit v1.2.3 From cb659d206463607b5387878a857ead770c4df8cc Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 6 Feb 2013 23:25:42 +0200 Subject: displaying lineno for 1-line snippet is overkill --- docs/narr/configuration.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index cd3dab099..820dda269 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -144,7 +144,6 @@ In the example above, the scanner translates the arguments to .. ignore-next-block .. code-block:: python - :linenos: config.add_view(hello) -- cgit v1.2.3 From 6a4c6cb1c6ebe148e948726ddf668a3c2aa6c86c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 6 Feb 2013 23:38:01 +0200 Subject: no need for a 'topic' directive --- docs/narr/configuration.rst | 44 +++++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index cd3dab099..4370367c0 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -99,29 +99,27 @@ available for a :term:`scan` to find it later. A :term:`scan` of a :term:`module` or a :term:`package` and its subpackages for decorations happens when the :meth:`pyramid.config.Configurator.scan` method is invoked: scanning implies searching for configuration declarations -in a package and its subpackages. For example: - -.. topic:: Starting A Scan - - .. code-block:: python - :linenos: - - from wsgiref.simple_server import make_server - from pyramid.config import Configurator - from pyramid.response import Response - from pyramid.view import view_config - - @view_config() - def hello(request): - return Response('Hello') - - if __name__ == '__main__': - from pyramid.config import Configurator - config = Configurator() - config.scan() - app = config.make_wsgi_app() - server = make_server('0.0.0.0', 8080, app) - server.serve_forever() +in a package and its subpackages. For example:: + +.. code-block:: python + :linenos: + + from wsgiref.simple_server import make_server + from pyramid.config import Configurator + from pyramid.response import Response + from pyramid.view import view_config + + @view_config() + def hello(request): + return Response('Hello') + + if __name__ == '__main__': + from pyramid.config import Configurator + config = Configurator() + config.scan() + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects -- cgit v1.2.3 From c7e558156dff1c8fdc96fe0382e48ca4d5bf8205 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 8 Feb 2013 20:48:08 +0200 Subject: fix a Sphinx warning --- docs/narr/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index cc26c55d9..6f82baf32 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -99,7 +99,7 @@ available for a :term:`scan` to find it later. A :term:`scan` of a :term:`module` or a :term:`package` and its subpackages for decorations happens when the :meth:`pyramid.config.Configurator.scan` method is invoked: scanning implies searching for configuration declarations -in a package and its subpackages. For example:: +in a package and its subpackages. For example: .. code-block:: python :linenos: -- cgit v1.2.3 From 1bdfad6c7303a810b05c60c53443dacc4d111852 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Feb 2013 00:47:47 +0200 Subject: remove obvious, and therefore redundant, info --- docs/narr/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index b092f73bc..85dfd5bf4 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -203,7 +203,7 @@ Installing Distribute On Python 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``setuptools`` doesn't work under Python 3. Instead, you can use -``distribute``, which is a fork of setuptools that does work on Python 3. To +``distribute``, which is a fork of setuptools. To install it, first download `distribute_setup.py `_ then invoke it using the Python interpreter into which you want to install setuptools. -- cgit v1.2.3 From 268737d1e1162867e4324f3400acaf158675ad6a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Feb 2013 14:16:49 +0200 Subject: grammar --- docs/api/request.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api/request.rst b/docs/api/request.rst index 9f1f71b31..7b843f86e 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -245,7 +245,7 @@ influence response values from a view that uses a renderer (such as the status code, a header, the content type, etc) you would set these attributes. See :ref:`response_prefixed_attrs` for further discussion. - As of Pyramid 1.1, assignment to ``response_*`` attrs are deprecated. + As of Pyramid 1.1, assignment to ``response_*`` attrs is deprecated. Assigning to one is still supported but will cause a deprecation warning to be emitted, and eventually the feature will be removed. For new code, instead of assigning ``response_*`` attributes to the -- cgit v1.2.3 From 0d40143635c5a248453b881247db66d2ba1f8d00 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Feb 2013 14:17:56 +0200 Subject: avoid repetition; the heading already mentions that this stuff is deprecated --- docs/narr/renderers.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 863932e83..34b9ad00c 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -565,9 +565,6 @@ in :ref:`request_module`. For more information on the API of Deprecated Mechanism to Vary Attributes of Rendered Responses ------------------------------------------------------------- -.. deprecated:: 1.1 - The behavior described in this entire section. - In previous releases of Pyramid (1.0 and before), the ``request.response`` attribute did not exist. Instead, Pyramid required users to set special ``response_`` -prefixed attributes of the request to influence response -- cgit v1.2.3 From c7a06f41d56d076dc979d800388c8befc1b8e5e5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 9 Feb 2013 19:54:32 -0500 Subject: fix warning block for newer docutils versions --- docs/narr/hooks.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 43bf48289..7d4d03b89 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -276,8 +276,10 @@ A lazy property can be registered to the request object via the to specify a callable that will be available on the request object, but will not actually execute the function until accessed. -.. warning:: This will silently override methods and properties from - :term:`request factory` that have the same name. +.. warning:: + + This will silently override methods and properties from :term:`request + factory` that have the same name. .. code-block:: python :linenos: -- cgit v1.2.3 From 182686ca798806a16b4d18e8bae49d5139477428 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 10 Feb 2013 13:29:53 +0200 Subject: bring back the intershinx goodness This ensures that links to external objects are 'magically' generated. This feature was disable in commit 288072c, but it was likely not used at the time. --- docs/conf.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 6eb76af9d..192bd7a79 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,20 +50,20 @@ extensions = [ 'sphinx.ext.doctest', 'repoze.sphinx.autointerface', 'sphinx.ext.viewcode', -# 'sphinx.ext.intersphinx' + 'sphinx.ext.intersphinx' ] -# Looks for objects in other Pyramid projects -## intersphinx_mapping = { -## 'cookbook': -## ('http://docs.pylonsproject.org/projects/pyramid_cookbook/dev/', None), -## 'handlers': -## ('http://docs.pylonsproject.org/projects/pyramid_handlers/dev/', None), -## 'zcml': -## ('http://docs.pylonsproject.org/projects/pyramid_zcml/dev/', None), -## 'jinja2': -## ('http://docs.pylonsproject.org/projects/pyramid_jinja2/dev/', None), -## } +# Looks for objects in external projects +intersphinx_mapping = { + 'who': ('http://docs.repoze.org/who/2.0', None), + 'python': ('http://docs.python.org', None), + 'python3': ('http://docs.python.org/3', None), + 'tstring': + ('http://docs.pylonsproject.org/projects/translationstring/en/latest', + None), + 'venusian': + ('http://docs.pylonsproject.org/projects/venusian/en/latest', None), +} # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -- cgit v1.2.3 From e3ed0ee85d3edc49740637e3bf76a04f1e6a6963 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 10 Feb 2013 13:31:12 +0200 Subject: use a more approriate Sphinx directive --- docs/narr/subrequest.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst index b5bc5ec48..033f045a6 100644 --- a/docs/narr/subrequest.rst +++ b/docs/narr/subrequest.rst @@ -6,9 +6,7 @@ Invoking a Subrequest ===================== -.. warning:: - - This feature was added in Pyramid 1.4a1. +.. versionadded:: 1.4 :app:`Pyramid` allows you to invoke a subrequest at any point during the processing of a request. Invoking a subrequest allows you to obtain a -- cgit v1.2.3 From 179f8c3e5c96ebef06710a0c214409aadd94ada5 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 10 Feb 2013 14:48:55 +0200 Subject: spaces are preferred to tabs --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 192bd7a79..8d22d4d42 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -62,7 +62,7 @@ intersphinx_mapping = { ('http://docs.pylonsproject.org/projects/translationstring/en/latest', None), 'venusian': - ('http://docs.pylonsproject.org/projects/venusian/en/latest', None), + ('http://docs.pylonsproject.org/projects/venusian/en/latest', None), } # Add any paths that contain templates here, relative to this directory. -- 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') 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 8c952d940272d883169973833ca215ac3248e94e Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 13 Feb 2013 18:28:37 -0600 Subject: add import in code block --- docs/narr/renderers.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 34b9ad00c..08ebd881e 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -316,6 +316,7 @@ time "by hand". Configure a JSONP renderer using the .. code-block:: python from pyramid.config import Configurator + from pyramid.renderers import JSONP config = Configurator() config.add_renderer('jsonp', JSONP(param_name='callback')) -- cgit v1.2.3 From a33ac9438f62c6d85263c772d601d77e1b2b1e3c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Feb 2013 00:25:06 +0200 Subject: paster use is outdated --- docs/narr/environment.rst | 2 +- docs/tutorials/wiki/NOTE-relocatable.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 281bb6919..fb3c3d7e3 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -546,7 +546,7 @@ for settings documented as such. For example, you might start your .. code-block:: text $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \ - bin/paster serve MyProject.ini + bin/pserve MyProject.ini If you started your application this way, your :app:`Pyramid` application would behave in the same manner as if you had placed the diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt index cec2639f3..4c778ad04 100644 --- a/docs/tutorials/wiki/NOTE-relocatable.txt +++ b/docs/tutorials/wiki/NOTE-relocatable.txt @@ -1,5 +1,5 @@ We specifically use relative package references where possible so this demo -works even if the user names their package (in the 'bin/paster create -t +works even if the user names their package (in the 'bin/pcreate -s zodb ...' step) something other than 'tutorial'. Specifically: -- cgit v1.2.3 From 5b966a49227cbb9702d2b085b3658e3c91d9eed7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 12:17:13 +0200 Subject: simplify sentence and fix its grammar --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 860c380f3..b9330b881 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -176,7 +176,7 @@ exception` objects. HTTP Exceptions ~~~~~~~~~~~~~~~ -All classes documented in the :mod:`pyramid.httpexceptions` module documented +All :mod:`pyramid.httpexceptions` classes which are documented as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are :term:`http exception` objects. Instances of an HTTP exception object may either be *returned* or *raised* from within view code. In either case -- cgit v1.2.3 From 2afc385f203be30638db41673b3a771772184c81 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 12:36:06 +0200 Subject: make easier on the eyes Also fixes grammar, and removes repetition. --- docs/narr/views.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 860c380f3..7acec49e5 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -236,12 +236,11 @@ How Pyramid Uses HTTP Exceptions HTTP exceptions are meant to be used directly by application developers. However, Pyramid itself will raise two HTTP exceptions at various points during normal operations: -:exc:`pyramid.httpexceptions.HTTPNotFound` and -:exc:`pyramid.httpexceptions.HTTPForbidden`. Pyramid will raise the -:exc:`~pyramid.httpexceptions.HTTPNotFound` exception are raised when it -cannot find a view to service a request. Pyramid will raise the -:exc:`~pyramid.httpexceptions.Forbidden` exception or when authorization was -forbidden by a security policy. + +* :exc:`~pyramid.httpexceptions.HTTPNotFound` + gets raised when a view to service a request is not found. +* :exc:`~pyramid.httpexceptions.HTTPForbidden` + gets raised when authorization was forbidden by a security policy. If :exc:`~pyramid.httpexceptions.HTTPNotFound` is raised by Pyramid itself or within view code, the result of the :term:`Not Found View` will be returned -- cgit v1.2.3 From 580d74db2a032fa6c84662d1d89362f83d068d48 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 12:42:52 +0200 Subject: replace awkward explanation --- docs/narr/hooks.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 7d4d03b89..f38d57e73 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -15,9 +15,8 @@ Changing the Not Found View --------------------------- When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`not -found view`, which is a :term:`view callable`. A default notfound view -exists. The default not found view can be overridden through application -configuration. +found view`, which is a :term:`view callable`. The default Not Found View +can be overridden through application configuration. If your application uses :term:`imperative configuration`, you can replace the Not Found view by using the -- cgit v1.2.3 From 1fbbb4dd9b4b735e1ba91f8eb25829ac96833566 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 18:58:16 +0200 Subject: this info was given in the preceding paragraph --- docs/narr/viewconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 7001cd980..eafec164e 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -68,7 +68,7 @@ the registered view callable will be invoked. The fewer number of predicates which are supplied to a particular view configuration, the more likely it is that the associated view callable will be invoked. A view with five predicates will always be found and evaluated before a view with two, for -example. All predicates must match for the associated view to be called. +example. This does not mean however, that :app:`Pyramid` "stops looking" when it finds a view registration with predicates that don't match. If one set -- cgit v1.2.3 From dd1970db763f3114a77ae1c98a3e529562fbfeb5 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 24 Feb 2013 15:03:26 +0200 Subject: virtualenv refers both to the tool and the concept --- docs/glossary.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 9220e6b5f..7bc5799f3 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -146,10 +146,9 @@ Glossary request before it returns a :term:`context` resource. virtualenv - An isolated Python environment. Allows you to control which - packages are used on a particular project by cloning your main - Python. `virtualenv `_ - was created by Ian Bicking. + A term referring both to an isolated Python environment, + or `the leading tool `_ that allows one to + create such environments. resource An object representing a node in the :term:`resource tree` of an @@ -959,7 +958,7 @@ Glossary console script A script written to the ``bin`` (on UNIX, or ``Scripts`` on Windows) - directory of a Python installation or virtualenv as the result of + directory of a Python installation or :term:`virtualenv` as the result of running ``setup.py install`` or ``setup.py develop``. introspector -- cgit v1.2.3 From c0e0acd981a1bfbcf4c039e0439ea183d3ce41bf Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 25 Feb 2013 08:07:15 +0200 Subject: grammar --- docs/narr/viewconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 7001cd980..2d4caab40 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -293,7 +293,7 @@ configured view. This value can be any string or a sequence of strings. A view declaration with this argument ensures that the view will only be called when the :term:`request` has a key in the ``request.params`` dictionary (an HTTP - ``GET`` or ``POST`` variable) that has a name which matches the a + ``GET`` or ``POST`` variable) that has a name which matches the supplied value. If any value supplied has a ``=`` sign in it, -- cgit v1.2.3 From 58661e6744a9588e84988c2b02b4ebb913ab0ac3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 26 Feb 2013 01:50:02 +0200 Subject: grammar --- docs/narr/viewconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 2d4caab40..e7c79b09b 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -475,7 +475,7 @@ Adding View Configuration Using the ``@view_config`` Decorator .. warning:: - Using this feature tends to slows down application startup slightly, as + Using this feature tends to slow down application startup slightly, as more work is performed at application startup to scan for view configuration declarations. For maximum startup performance, use the view configuration method described in -- cgit v1.2.3 From 8b96432b0c285ae5422ef32c8e97284b20e7f678 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 26 Feb 2013 02:16:14 +0200 Subject: improve paragraph --- docs/narr/viewconfig.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 7001cd980..126d7fd06 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -706,11 +706,10 @@ this method are very similar to the arguments that you provide to the # pyramid.config.Configurator class config.add_view(hello_world, route_name='hello') -The first argument, ``view``, is required. It must either be a Python object -which is the view itself or a :term:`dotted Python name` to such an object. -In the above example, ``view`` is the ``hello_world`` function. All other -arguments are optional. See :meth:`pyramid.config.Configurator.add_view` for -more information. +The first argument, a :term:`view callable`, is the only required argument. +It must either be a Python object which is the view itself or a +:term:`dotted Python name` to such an object. +In the above example, the ``view callable`` is the ``hello_world`` function. When you use only :meth:`~pyramid.config.Configurator.add_view` to add view configurations, you don't need to issue a :term:`scan` in order for the view -- cgit v1.2.3 From 16f2011492d96f1e6169bfbd05cd003192b07329 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 26 Feb 2013 23:08:10 +0200 Subject: grammar --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6a1fbf916..89024a34e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -621,7 +621,7 @@ Debugging Templates ------------------- A :exc:`NameError` exception resulting from rendering a template with an -undefined variable (e.g. ``${wrong}``) might will end like this: +undefined variable (e.g. ``${wrong}``) might end up looking like this: .. code-block:: text -- 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') 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 ca402b50f2440b3ab7d7e0d9d058e72c20e9948b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 27 Feb 2013 23:15:12 +0200 Subject: should be one word --- docs/narr/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index 20017064b..d5624469c 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -70,7 +70,7 @@ Test Set Up and Tear Down -------------------------- :app:`Pyramid` uses a "global" (actually :term:`thread local`) data structure -to hold on to two items: the current :term:`request` and the current +to hold onto two items: the current :term:`request` and the current :term:`application registry`. These data structures are available via the :func:`pyramid.threadlocal.get_current_request` and :func:`pyramid.threadlocal.get_current_registry` functions, respectively. -- cgit v1.2.3 From 78080559e7add3203fbba64c03f2ae7d348cebb9 Mon Sep 17 00:00:00 2001 From: David Beitey Date: Thu, 28 Feb 2013 10:44:57 +1000 Subject: Update & clarify logging documentation Ensure that ``handlers`` is highlighted to be modified when adding an access log handler. --- docs/narr/logging.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4c38abb6..f4d1d051d 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -350,7 +350,7 @@ called with no arguments, so it 'just works' in environments that don't configure logging. Since we've configured our own logging handlers, we need to disable that option via ``setup_console_handler = False``. -With the filter in place, TransLogger's logger (named the 'wsgi' logger) will +With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will propagate its log messages to the parent logger (the root logger), sending its output to the console when we request a page: @@ -364,14 +364,18 @@ its output to the console when we request a page: Firefox/2.0.0.6" To direct TransLogger to an ``access.log`` FileHandler, we need to add that -FileHandler to the wsgi logger's list of handlers: +FileHandler to the list of handlers (named ``accesslog``), and ensure that the +``wsgi`` logger is configured and uses this handler accordingly: .. code-block:: ini # Begin logging configuration - [loggers] - keys = root, myapp, wsgi + [loggers] + keys = root, myapp, wsgi + + [handlers] + keys = console, accesslog [logger_wsgi] level = INFO @@ -387,20 +391,19 @@ FileHandler to the wsgi logger's list of handlers: As mentioned above, non-root loggers by default propagate their log records to the root logger's handlers (currently the console handler). Setting -``propagate`` to 0 (false) here disables this; so the ``wsgi`` logger directs -its records only to the ``accesslog`` handler. +``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger +directs its records only to the ``accesslog`` handler. Finally, there's no need to use the ``generic`` formatter with TransLogger as TransLogger itself provides all the information we need. We'll use a -formatter that passes-through the log messages as is: +formatter that passes-through the log messages as is. Add a new formatter +called ``accesslog`` by include the following in your configuration file: .. code-block:: ini [formatters] keys = generic, accesslog -.. code-block:: ini - [formatter_accesslog] format = %(message)s -- cgit v1.2.3 From 9279d7ce253f70a17a0131ee061468d4600b20dc Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 2 Mar 2013 13:47:40 +0200 Subject: no need for a separate API file --- docs/api.rst | 41 ----------------------------------------- docs/index.rst | 7 ++++--- 2 files changed, 4 insertions(+), 44 deletions(-) delete mode 100644 docs/api.rst (limited to 'docs') diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 9e540b49b..000000000 --- a/docs/api.rst +++ /dev/null @@ -1,41 +0,0 @@ -API Documentation -================= - -Comprehensive reference material for every public API exposed by -:app:`Pyramid` is available within this chapter. The API -documentation is organized alphabetically by module name. - -.. toctree:: - :maxdepth: 1 - - api/authorization - api/authentication - api/compat - api/config - api/decorator - api/events - api/exceptions - api/httpexceptions - api/i18n - api/interfaces - api/location - api/paster - api/path - api/registry - api/renderers - api/request - api/response - api/scaffolds - api/scripting - api/security - api/session - api/settings - api/static - api/testing - api/threadlocal - api/traversal - api/tweens - api/url - api/view - api/wsgi - diff --git a/docs/index.rst b/docs/index.rst index d4b7ed492..6e2568a21 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -112,12 +112,13 @@ platforms. API Documentation ================== -Documentation for every :app:`Pyramid` API. +Comprehensive reference material for every public API exposed by :app:`Pyramid`: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :glob: - api + api/* Change History ============== -- cgit v1.2.3 From a85491f3cec005e9592c86bd78b66ec0d7a8e599 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Sun, 3 Mar 2013 15:41:37 -0500 Subject: No preposition needed at all. ;) --- docs/narr/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index d5624469c..0801a8eae 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -70,7 +70,7 @@ Test Set Up and Tear Down -------------------------- :app:`Pyramid` uses a "global" (actually :term:`thread local`) data structure -to hold onto two items: the current :term:`request` and the current +to hold two items: the current :term:`request` and the current :term:`application registry`. These data structures are available via the :func:`pyramid.threadlocal.get_current_request` and :func:`pyramid.threadlocal.get_current_registry` functions, respectively. -- 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/MyProject/setup.py | 6 ++++-- docs/narr/commandline.rst | 12 ++++++++---- docs/tutorials/wiki/src/authorization/setup.py | 6 ++++-- docs/tutorials/wiki/src/basiclayout/setup.py | 6 ++++-- docs/tutorials/wiki/src/models/setup.py | 6 ++++-- docs/tutorials/wiki/src/tests/setup.py | 6 ++++-- docs/tutorials/wiki/src/views/setup.py | 6 ++++-- docs/tutorials/wiki/tests.rst | 2 +- docs/tutorials/wiki2/definingviews.rst | 2 +- docs/tutorials/wiki2/src/authorization/setup.py | 6 ++++-- docs/tutorials/wiki2/src/basiclayout/setup.py | 6 ++++-- docs/tutorials/wiki2/src/models/setup.py | 6 ++++-- docs/tutorials/wiki2/src/tests/setup.py | 6 ++++-- docs/tutorials/wiki2/src/views/setup.py | 6 ++++-- docs/tutorials/wiki2/tests.rst | 2 +- 15 files changed, 55 insertions(+), 29 deletions(-) (limited to 'docs') diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py index f24b6984e..6969c73e7 100644 --- a/docs/narr/MyProject/setup.py +++ b/docs/narr/MyProject/setup.py @@ -3,8 +3,10 @@ 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() +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', 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'] diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py index 3164fd724..5d87fedbf 100644 --- a/docs/tutorials/wiki/src/authorization/setup.py +++ b/docs/tutorials/wiki/src/authorization/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py index 4998be902..75ba02611 100644 --- a/docs/tutorials/wiki/src/basiclayout/setup.py +++ b/docs/tutorials/wiki/src/basiclayout/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py index 4998be902..75ba02611 100644 --- a/docs/tutorials/wiki/src/models/setup.py +++ b/docs/tutorials/wiki/src/models/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py index 702d34c4c..5ff7b545c 100644 --- a/docs/tutorials/wiki/src/tests/setup.py +++ b/docs/tutorials/wiki/src/tests/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py index 3164fd724..5d87fedbf 100644 --- a/docs/tutorials/wiki/src/views/setup.py +++ b/docs/tutorials/wiki/src/views/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index 49bc780e8..36ae7930b 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -59,7 +59,7 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``. .. literalinclude:: src/tests/setup.py :linenos: :language: python - :lines: 9-19 + :lines: 11-21 :emphasize-lines: 10 After we've added a dependency on WebTest in ``setup.py``, we need to rerun diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index e83a88198..0e95ca1c1 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -33,7 +33,7 @@ Open ``tutorial/setup.py`` and edit it to look like the following: .. literalinclude:: src/views/setup.py :linenos: :language: python - :emphasize-lines: 17 + :emphasize-lines: 19 (Only the highlighted line needs to be added.) diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py index 36668dd33..e8fa8f396 100644 --- a/docs/tutorials/wiki2/src/authorization/setup.py +++ b/docs/tutorials/wiki2/src/authorization/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py index a09bf756a..e7d318128 100644 --- a/docs/tutorials/wiki2/src/basiclayout/setup.py +++ b/docs/tutorials/wiki2/src/basiclayout/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py index a09bf756a..e7d318128 100644 --- a/docs/tutorials/wiki2/src/models/setup.py +++ b/docs/tutorials/wiki2/src/models/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py index 3c2961fcc..c3da36b39 100644 --- a/docs/tutorials/wiki2/src/tests/setup.py +++ b/docs/tutorials/wiki2/src/tests/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py index 36668dd33..e8fa8f396 100644 --- a/docs/tutorials/wiki2/src/views/setup.py +++ b/docs/tutorials/wiki2/src/views/setup.py @@ -3,8 +3,10 @@ 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() +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', diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index 83df86b27..7aa3c464d 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -54,7 +54,7 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``. .. literalinclude:: src/tests/setup.py :linenos: :language: python - :lines: 9-20 + :lines: 11-21 :emphasize-lines: 10 After we've added a dependency on WebTest in ``setup.py``, we need to rerun -- cgit v1.2.3 From 2605e0cc2ad089d4f25c00a5f2c4d99ffbfa4567 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 22:57:05 +0200 Subject: grammar fixes --- docs/narr/project.rst | 4 ++-- docs/narr/router.rst | 2 +- docs/narr/urldispatch.rst | 8 ++++---- docs/narr/viewconfig.rst | 4 ++-- 4 files changed, 9 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5a8ea0ecf..184d36512 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -829,7 +829,7 @@ also informs Python that the directory which contains it is a *package*. #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config` that we use later. -#. Lines 4-11 define a function named ``main`` that returns a :app:`Pyramid` +#. Lines 4-11 defines a function named ``main`` that returns a :app:`Pyramid` WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. @@ -865,7 +865,7 @@ and which returns a :term:`response`. :language: python :linenos: -Lines 4-6 define and register a :term:`view callable` named ``my_view``. The +Lines 4-6 defines and registers a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). The view_config decorator asserts that this view be found when a diff --git a/docs/narr/router.rst b/docs/narr/router.rst index b78362066..ac3deefdc 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -46,7 +46,7 @@ request enters a :app:`Pyramid` application through to the point that :class:`~pyramid.interfaces.IRoute` object representing the route which matched. The root object associated with the route found is also generated: if the :term:`route configuration` which matched has an - associated a ``factory`` argument, this factory is used to generate the + associated ``factory`` argument, this factory is used to generate the root object, otherwise a default :term:`root factory` is used. #. If a route match was *not* found, and a ``root_factory`` argument was diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 749a2d49a..34543c4bb 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -16,12 +16,12 @@ receives the :term:`request` and returns a :term:`response` object. High-Level Operational Overview ------------------------------- -If route configuration is present in an application, the :app:`Pyramid` +If a route configuration is present in an application, the :app:`Pyramid` :term:`Router` checks every incoming request against an ordered set of URL matching patterns present in a *route map*. If any route pattern matches the information in the :term:`request`, -:app:`Pyramid` will invoke :term:`view lookup` to find a matching view. +:app:`Pyramid` will invoke a :term:`view lookup` to find a matching view. If no route pattern in the route map matches the information in the :term:`request` provided in your application, :app:`Pyramid` will fail over @@ -71,7 +71,7 @@ invoked when the associated route pattern matches during a request. More commonly, you will not use any ``add_view`` statements in your project's "setup" code, instead only using ``add_route`` statements using a -:term:`scan` for to associate view callables with routes. For example, if +:term:`scan` to associate view callables with routes. For example, if this is a portion of your project's ``__init__.py``: .. code-block:: python @@ -83,7 +83,7 @@ this is a portion of your project's ``__init__.py``: Note that we don't call :meth:`~pyramid.config.Configurator.add_view` in this setup code. However, the above :term:`scan` execution -``config.scan('mypackage')`` will pick up all :term:`configuration +``config.scan('mypackage')`` will pick up each :term:`configuration decoration`, including any objects decorated with the :class:`pyramid.view.view_config` decorator in the ``mypackage`` Python package. For example, if you have a ``views.py`` in your package, a scan will diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index e7c79b09b..63f9d1db5 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -62,9 +62,9 @@ particular view callable. :term:`View predicate` attributes are an important part of view configuration that enables the :term:`view lookup` subsystem to find and invoke the -appropriate view. The greater number of predicate attributes possessed by a +appropriate view. The greater the number of predicate attributes possessed by a view's configuration, the more specific the circumstances need to be before -the registered view callable will be invoked. The fewer number of predicates +the registered view callable will be invoked. The fewer the number of predicates which are supplied to a particular view configuration, the more likely it is that the associated view callable will be invoked. A view with five predicates will always be found and evaluated before a view with two, for -- cgit v1.2.3 From cd8ac801ac1ccefb81c2e015124be910cb8c93de Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 15 Feb 2013 00:48:08 +0200 Subject: update some links and fix others --- docs/designdefense.rst | 2 +- docs/index.rst | 4 ++-- docs/narr/hooks.rst | 2 +- docs/tutorials/wiki/definingviews.rst | 2 +- docs/tutorials/wiki2/definingviews.rst | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 69a921498..ffcb6c5b1 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1030,7 +1030,7 @@ but its intended userbase is much the same. Many others exist. We've actually even (only as a teaching tool, not as any sort of official project) `created one using Pyramid `_ (the videos use BFG, a precursor to Pyramid, but the resulting code is `available -for Pyramid too `_). Microframeworks are +for Pyramid too `_). Microframeworks are small frameworks with one common feature: each allows its users to create a fully functional application that lives in a single Python file. diff --git a/docs/index.rst b/docs/index.rst index 6e2568a21..bc711f8ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -189,7 +189,7 @@ The `Pylons Project web site `_ is the main online source of :app:`Pyramid` support and development information. To report bugs, use the `issue tracker -`_. +`_. If you've got questions that aren't answered by this documentation, contact the `Pylons-discuss maillist @@ -197,7 +197,7 @@ contact the `Pylons-discuss maillist IRC channel `_. Browse and check out tagged and trunk versions of :app:`Pyramid` via -the `Pyramid GitHub repository `_. +the `Pyramid GitHub repository `_. To check out the trunk via ``git``, use this command: .. code-block:: text diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index f38d57e73..20cadc996 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -711,7 +711,7 @@ The API that must be implemented by your a class that provides The default context URL generator is available for perusal as the class :class:`pyramid.traversal.ResourceURL` in the `traversal module -`_ of the +`_ of the :term:`Pylons` GitHub Pyramid repository. See :meth:`pyramid.config.add_resource_url_adapter` for more information. diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 4dedf4320..23ee142af 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -317,7 +317,7 @@ Our templates name a single static asset named ``pylons.css``. We don't need to create this file within our package's ``static`` directory because it was provided at the time we created the project. This file is a little too long to replicate within the body of this guide, however it is available `online -`_. +`_. This CSS file will be accessed via e.g. ``/static/pylons.css`` by virtue of the call to diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 0e95ca1c1..9d2f8fb7f 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -287,7 +287,7 @@ Our templates name a single static asset named ``pylons.css``. We don't need to create this file within our package's ``static`` directory because it was provided at the time we created the project. This file is a little too long to replicate within the body of this guide, however it is available `online -`_. +`_. This CSS file will be accessed via e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to -- cgit v1.2.3 From 62ea1b60f18d8ac0bab2331852f9ef8bee1fad57 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 01:10:49 +0200 Subject: fix link --- docs/narr/paste.rst | 2 ++ docs/narr/startup.rst | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 86b047aec..efec1f092 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -85,6 +85,8 @@ function. This is the function called by :term:`PasteDeploy` when the ``pserve`` command is invoked against our application. It accepts a global configuration object and *returns* an instance of our application. +.. _defaults_section_of_pastedeploy_file: + ``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index f5c741f52..3a9225032 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -77,9 +77,9 @@ Here's a high-level time-ordered overview of what happens when you press Note that the constructor function accepts a ``global_config`` argument, which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]`` - section of an ``.ini`` file (if `[DEFAULT] - `__ - is present). It also accepts a ``**settings`` argument, which collects + section of an ``.ini`` file + (if :ref:`[DEFAULT] ` is present). + It also accepts a ``**settings`` argument, which collects another set of arbitrary key/value pairs. The arbitrary key/value pairs received by this function in ``**settings`` will be composed of all the key/value pairs that are present in the ``[app:main]`` section (except for -- cgit v1.2.3 From 44b651726b030c106aa5d2ff6ecdd5ba47f6c662 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 13:06:07 +0200 Subject: update link --- docs/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 9220e6b5f..2d05cde03 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -324,8 +324,8 @@ Glossary `A full-featured Python web framework `_. Pylons - `A lightweight Python web framework `_ and a - predecessor of Pyramid. + `A lightweight Python web framework `_ + and a predecessor of Pyramid. ZODB `Zope Object Database `_, a -- cgit v1.2.3 From 32c508a8d8870e877dd6d98e717e55b56457de8a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 21:50:53 +0200 Subject: use cross-references to fix some links Also fix grammar, and add a bit of consistency regarding formatting. --- docs/narr/logging.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4d1d051d..bef9d119c 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -28,19 +28,17 @@ application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use a scaffold include a basic configuration for the Python :mod:`logging` package. -PasteDeploy ``.ini`` files use the Python standard library `ConfigParser -format `_; this the same -format used as the Python `logging module's Configuration file format -`_. The -application-related and logging-related sections in the configuration file +PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser +format `; this is the same format used as the Python +:ref:`logging module's Configuration file format `. +The application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used from when you run ``pserve``. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` -function, a thin wrapper around the `logging.fileConfig -`_ using the specified -ini file if it contains a ``[loggers]`` section (all of the -scaffold-generated ``.ini`` files do). ``setup_logging`` reads the +function, a thin wrapper around the :func:`logging.config.fileConfig` +using the specified ``.ini`` file if it contains a ``[loggers]`` section +(all of the scaffold-generated ``.ini`` files do). ``setup_logging`` reads the logging configuration from the ini file upon which ``pserve`` was invoked. -- cgit v1.2.3 From eb71e9ef30a0edb43129c24c56885a6c3d61a3a3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Feb 2013 12:15:52 +0200 Subject: make it clear where the link goes --- docs/glossary.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 2d05cde03..eedd2f34f 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -654,10 +654,9 @@ Glossary `_ used by the application may have a different value for this same "global" variable. :app:`Pyramid` uses a small number of thread local variables, as - described in :ref:`threadlocals_chapter`. See also the `threading.local - documentation - `_ for - more information. + described in :ref:`threadlocals_chapter`. + See also the :class:`stdlib documentation ` + for more information. multidict An ordered dictionary that can have multiple values for each key. Adds -- cgit v1.2.3 From 6ad5fb2a48c9a0c081eb3e2b138752bc8c4e63fb Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 18 Feb 2013 23:14:16 +0200 Subject: fix links --- docs/glossary.rst | 2 +- docs/narr/paste.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index eedd2f34f..d3176325f 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -342,7 +342,7 @@ Glossary library created by Ian Bicking. PasteDeploy - `PasteDeploy `_ is a library used by + `PasteDeploy `_ is a library used by :app:`Pyramid` which makes it possible to configure :term:`WSGI` components together declaratively within an ``.ini`` file. It was developed by Ian Bicking. diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index efec1f092..0b3457d1e 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -21,7 +21,7 @@ of starting, stopping, and debugging an application. This chapter is not a replacement for documentation about PasteDeploy; it only contextualizes the use of PasteDeploy within Pyramid. For detailed -documentation, see http://pythonpaste.org. +documentation, see http://pythonpaste.org/deploy/. PasteDeploy ----------- -- cgit v1.2.3 From cff8573673d919fd0fc3b283bef03923e1db54b5 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 19 Feb 2013 23:15:36 +0200 Subject: update links --- docs/designdefense.rst | 2 +- docs/glossary.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index ffcb6c5b1..749c9b099 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -238,7 +238,7 @@ registry API. :app:`Pyramid` framework developers were so concerned about conceptual load issues of the ZCA registry API for framework developers that a `replacement -registry implementation `_ +registry implementation `_ named :mod:`repoze.component` was actually developed. Though this package has a registry implementation which is fully functional and well-tested, and its API is much nicer than the ZCA registry API, work on it was largely diff --git a/docs/glossary.rst b/docs/glossary.rst index d3176325f..75bc126f8 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -684,7 +684,7 @@ Glossary The C implementation of the Python language. This is the reference implementation that most people refer to as simply "Python"; :term:`Jython`, Google's App Engine, and `PyPy - `_ are examples of + `_ are examples of non-C based Python implementations. View Lookup -- cgit v1.2.3 From 75ebabe886bbbe14c873e60597f16531c151a867 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 19 Feb 2013 23:26:45 +0200 Subject: fix broken link --- docs/narr/i18n.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 511464322..24cd3ff54 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -736,9 +736,7 @@ through translation before being rendered: The features represented by attributes of the ``i18n`` namespace of Chameleon will also consult the :app:`Pyramid` translations. -See -`http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace -`_. +See http://chameleon.readthedocs.org/en/latest/reference.html#id50. .. note:: -- cgit v1.2.3 From 9547903b00196b7311b6f0c26f42fed78a91e933 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 19 Feb 2013 23:34:56 +0200 Subject: rm broken link; could not find existing equivalent --- docs/narr/introduction.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 3540ee5c4..47c32b0ba 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -219,7 +219,6 @@ that the Pyramid core doesn't. Add-on packages already exist which let you easily send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc. -Examples: http://docs.pylonsproject.org/docs/pyramid.html#pyramid-add-on-documentation Class-based and function-based views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 8087fb7b72a8642ce3a323692b828d87369cff9f Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 19 Feb 2013 23:40:04 +0200 Subject: fix broken links --- docs/whatsnew-1.0.rst | 2 +- docs/whatsnew-1.3.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 66cb9be3a..d1f3046ca 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -249,7 +249,7 @@ ZCML Externalized Pyramid core. Loading ZCML is now a feature of the :term:`pyramid_zcml` package, which can be downloaded from PyPI. Documentation for the package should be available via - http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how to + http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, which describes how to add a configuration statement to your ``main`` block to reobtain this method. You will also need to add an ``install_requires`` dependency upon the ``pyramid_zcml`` distribution to your ``setup.py`` file. diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index f32053202..dfc7b4f4b 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -524,7 +524,7 @@ Documentation Enhancements - Removed the "Running Pyramid on Google App Engine" tutorial from the main docs. It survives on in the Cookbook - (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/gae.html). + (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gae.html). Rationale: it provides the correct info for the Python 2.5 version of GAE only, and this version of Pyramid does not support Python 2.5. -- cgit v1.2.3 From 04a662656deeafe0a8db61d29c64733181badb73 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 11:55:14 +0200 Subject: DRY --- docs/narr/firstapp.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index d61d95685..ab6a46c2f 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -175,9 +175,9 @@ First line above calls the :meth:`pyramid.config.Configurator.add_route` method, which registers a :term:`route` to match any URL path that begins with ``/hello/`` followed by a string. -The second line, ``config.add_view(hello_world, route_name='hello')``, -registers the ``hello_world`` function as a :term:`view callable` and makes -sure that it will be called when the ``hello`` route is matched. +The second line registers the ``hello_world`` function as a +:term:`view callable` and makes sure that it will be called when the +``hello`` route is matched. .. index:: single: make_wsgi_app -- cgit v1.2.3 From 3284496e797e07695a2b190b83619fc34f670d0a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 22:45:09 +0200 Subject: DRY --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5a8ea0ecf..5ddf89ec4 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -703,7 +703,7 @@ work properly. The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as -testing your application, packaging, and distributing your application. +testing, packaging, and distributing your application. .. note:: -- cgit v1.2.3 From 5c9da6debe11b52975fb296be55a4dcd8c41c533 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Feb 2013 22:35:32 +0200 Subject: DRY --- docs/narr/urldispatch.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 749a2d49a..6cdcd81fb 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -76,8 +76,6 @@ this is a portion of your project's ``__init__.py``: .. code-block:: python - # in your project's __init__.py (mypackage.__init__) - config.add_route('myroute', '/prefix/{one}/{two}') config.scan('mypackage') -- cgit v1.2.3 From 67486e9eec17b0209aebc9b2f2220fa704f23825 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Feb 2013 22:47:39 +0200 Subject: DRY --- docs/narr/urldispatch.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 6cdcd81fb..2a7adea81 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -90,8 +90,6 @@ that references ``myroute`` as a ``route_name`` parameter: .. code-block:: python - # in your project's views.py module (mypackage.views) - from pyramid.view import view_config from pyramid.response import Response -- cgit v1.2.3 From 08f4a6ea291e065e56792ecde89abdeb0c57651f Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 18:07:35 +0200 Subject: a more concise explanation * This removes an needless example (it should really be obvious what the text means). * It also fixes an incomplete sentence, which also happens to have broken grammar. --- docs/narr/project.rst | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5a8ea0ecf..959583ee2 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -459,20 +459,9 @@ Put a hash mark at the beginning of the ``pyramid_debugtoolbar`` line: Then restart the application to see that the toolbar has been turned off. Note that if you comment out the ``pyramid_debugtoolbar`` line, the ``#`` -*must* be in the first column. If you put the hash mark anywhere except the -first column instead, for example like this: - -.. code-block:: ini - :linenos: - - [app:main] - ... - pyramid.includes = - #pyramid_debugtoolbar - -When you attempt to restart the application with a section like the above -you'll receive an error that ends something like this, and the application -will not start: +*must* be in the first column. If you put it anywhere else, +and then attempt to restart the application, +you'll receive an error that ends something like this: .. code-block:: text -- cgit v1.2.3 From c4c182b47d1abdf899077ecd433a268618f4f493 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 18:30:02 +0200 Subject: be more concise, and simplify * It should be obvious which file is referred to * Fix a typo * 'points at a string' is not ideal when referring to Python --- docs/narr/paste.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 86b047aec..aee5f9069 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -62,7 +62,7 @@ Take a look at the generated ``setup.py`` file for this project. :language: python :linenos: -Note that the ``entry_point`` line in ``setup.py`` points at a string which +Note that ``entry_points`` is assigned a string which looks a lot like an ``.ini`` file. This string representation of an ``.ini`` file has a section named ``[paste.app_factory]``. Within this section, there is a key named ``main`` (the entry point name) which has a value -- 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') 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 0e5cd0f81f5fe053217d13a633ce780ca4477161 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 10:19:01 +0200 Subject: typo --- docs/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 9220e6b5f..d6adaa787 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -18,7 +18,7 @@ Glossary response An object returned by a :term:`view callable` that represents response - data returned to the requesting user agent. It must implements the + data returned to the requesting user agent. It must implement the :class:`pyramid.interfaces.IResponse` interface. A response object is typically an instance of the :class:`pyramid.response.Response` class or a subclass such as :class:`pyramid.httpexceptions.HTTPFound`. See -- cgit v1.2.3 From 3144affbb05ecea581d0e1cc612a3e1672b55181 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 16:41:11 +0200 Subject: fix markup --- docs/narr/environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index fb3c3d7e3..c8a666b90 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -212,7 +212,7 @@ sequence can take several different forms. package1 package2 package3 - The package names can also be separated by carriage returns:: + The package names can also be separated by carriage returns:: package1 package2 -- cgit v1.2.3 From ea87985307731d1ad8597a8e37b7fb9c7950f11f Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 22:32:07 +0200 Subject: missing word --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4d1d051d..6492bf371 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -334,7 +334,7 @@ To this: mypyramidapp Using PasteDeploy this way to form and serve a pipeline is equivalent to -wrapping your app in a TransLogger instance via the bottom the ``main`` +wrapping your app in a TransLogger instance via the bottom of the ``main`` function of your project's ``__init__`` file: .. code-block:: python -- cgit v1.2.3 From 6a2827684a13bb588b031f4ac9a6257344bb4e18 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Feb 2013 22:47:53 +0200 Subject: fix grammar; shorten overlong sentence --- docs/narr/urldispatch.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 749a2d49a..7e460c885 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -70,8 +70,8 @@ via its ``route_name`` predicate, that view callable will always be found and invoked when the associated route pattern matches during a request. More commonly, you will not use any ``add_view`` statements in your project's -"setup" code, instead only using ``add_route`` statements using a -:term:`scan` for to associate view callables with routes. For example, if +"setup" code. You will instead use ``add_route`` statements, and use a +:term:`scan` to associate view callables with routes. For example, if this is a portion of your project's ``__init__.py``: .. code-block:: python -- cgit v1.2.3 From feee096963f9c64681210d1fd11de337a5c9afbc Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 13:01:48 +0200 Subject: add missing word, add a :term: role where it was missing, improve readability --- docs/narr/views.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 8ebdfe219..afc2787ca 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -264,9 +264,9 @@ also be used by application developers to convert arbitrary exceptions to responses. To register a view that should be called whenever a particular exception is -raised from with :app:`Pyramid` view code, use the exception class or one of -its superclasses as the ``context`` of a view configuration which points at a -view callable you'd like to generate a response. +raised from within :app:`Pyramid` view code, use the exception class (or one of +its superclasses) as the :term:`context` of a view configuration which points +at a view callable you'd like to generate a response for. For example, given the following exception class in a module named ``helloworld.exceptions``: -- cgit v1.2.3 From bdbf854c95406c06c5b5e1bf85a89e5c961424f0 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 18:26:32 +0200 Subject: we want 4-space indents --- docs/narr/views.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index afc2787ca..077d27366 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -542,7 +542,7 @@ The following types work as view callables in this style: from pyramid.response import Response def view(context, request): - return Response('OK') + return Response('OK') #. Classes that have an ``__init__`` method that accepts ``context, request`` and a ``__call__`` method which accepts no arguments, e.g.: @@ -553,12 +553,12 @@ The following types work as view callables in this style: from pyramid.response import Response class view(object): - def __init__(self, context, request): - self.context = context - self.request = request + def __init__(self, context, request): + self.context = context + self.request = request - def __call__(self): - return Response('OK') + def __call__(self): + return Response('OK') #. Arbitrary callables that have a ``__call__`` method that accepts ``context, request``, e.g.: @@ -569,8 +569,8 @@ The following types work as view callables in this style: from pyramid.response import Response class View(object): - def __call__(self, context, request): - return Response('OK') + def __call__(self, context, request): + return Response('OK') view = View() # this is the view callable This style of calling convention is most useful for :term:`traversal` based -- cgit v1.2.3 From 02e6877a79fe7874af5103d9e6c886d67a09eb7f Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 6 Mar 2013 00:09:54 +0200 Subject: address issues raised by Tres Seaver at #884 --- docs/narr/project.rst | 4 ++-- docs/narr/urldispatch.rst | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 184d36512..5a8ea0ecf 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -829,7 +829,7 @@ also informs Python that the directory which contains it is a *package*. #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config` that we use later. -#. Lines 4-11 defines a function named ``main`` that returns a :app:`Pyramid` +#. Lines 4-11 define a function named ``main`` that returns a :app:`Pyramid` WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. @@ -865,7 +865,7 @@ and which returns a :term:`response`. :language: python :linenos: -Lines 4-6 defines and registers a :term:`view callable` named ``my_view``. The +Lines 4-6 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). The view_config decorator asserts that this view be found when a diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 34543c4bb..e58d98416 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -16,12 +16,13 @@ receives the :term:`request` and returns a :term:`response` object. High-Level Operational Overview ------------------------------- -If a route configuration is present in an application, the :app:`Pyramid` +If any route configuration is present in an application, the :app:`Pyramid` :term:`Router` checks every incoming request against an ordered set of URL matching patterns present in a *route map*. If any route pattern matches the information in the :term:`request`, -:app:`Pyramid` will invoke a :term:`view lookup` to find a matching view. +:app:`Pyramid` will invoke the :term:`view lookup` process to find a +matching view. If no route pattern in the route map matches the information in the :term:`request` provided in your application, :app:`Pyramid` will fail over -- cgit v1.2.3 From 58577149d79ed4e5aae6a90423c5b43edd811987 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 6 Mar 2013 01:11:12 +0200 Subject: fix typo, and change meaning --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 89024a34e..08fa9883e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -524,7 +524,7 @@ And ``templates/mytemplate.pt`` might look like so: Using A Chameleon Macro Name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sommetime you'd like to render a macro inside of a Chameleon ZPT template +At times, you may want to render a macro inside of a Chameleon ZPT template instead of the full Chameleon ZPT template. To render the content of a ``define-macro`` field inside a Chameleon ZPT template, given a Chameleon template file named ``foo.pt`` and a macro named ``bar`` defined within it -- cgit v1.2.3 From 5477d876b755447f8620fc798668d4fb94eb7688 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 6 Mar 2013 00:50:45 -0800 Subject: Grammar fixes --- docs/tutorials/wiki/authorization.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index 7c8ba99bf..ff1e283ab 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -55,8 +55,8 @@ returns one of these values: - If the userid *does not* exist in the system, it will return ``None``. -For example, ``groupfinder('editor', request )`` returns ['group:editor'], -``groupfinder('viewer', request)`` returns [], and ``groupfinder('admin', request)`` +For example, ``groupfinder('editor', request )`` returns ``['group:editor']``, +``groupfinder('viewer', request)`` returns ``[]``, and ``groupfinder('admin', request)`` returns ``None``. We will use ``groupfinder()`` as an :term:`authentication policy` "callback" that will provide the :term:`principal` or principals for a user. @@ -85,7 +85,7 @@ Add the following lines to the ``Wiki`` class: :language: python We import :data:`~pyramid.security.Allow`, an action that -means that permission is allowed:, and +means that permission is allowed, and :data:`~pyramid.security.Everyone`, a special :term:`principal` that is associated to all requests. Both are used in the :term:`ACE` entries that make up the ACL. @@ -93,8 +93,8 @@ that is associated to all requests. Both are used in the The ACL is a list that needs to be named `__acl__` and be an attribute of a class. We define an :term:`ACL` with two :term:`ACE` entries: the first entry allows any user the `view` -permission. The second entry allows the ``group:editors`` -principal the `edit` permission. +permission, and the second entry allows the ``group:editors`` +principal the `edit` permission. The ``Wiki`` class that contains the ACL is the :term:`resource` constructor for the :term:`root` resource, which is @@ -104,7 +104,7 @@ the ``context`` attribute. It's only happenstance that we're assigning this ACL at class scope. An ACL can be attached to an object *instance* too; this is how "row level security" -can be achieved in :app:`Pyramid` applications. We actually only need *one* +can be achieved in :app:`Pyramid` applications. We actually need only *one* ACL for the entire system, however, because our security requirements are simple, so this feature is not demonstrated. See :ref:`assigning_acls` for more information about what an @@ -144,13 +144,13 @@ machinery represented by this policy: it is required. The ``callback`` is the Add permission declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add a ``permission='edit'`` parameter to the ``@view_config`` -decorator for ``add_page()`` and ``edit_page()``, for example: +Open ``tutorial/views.py``. Add a ``permission='edit'`` parameter +to the ``@view_config`` decorator for ``add_page()`` and +``edit_page()``, for example: .. code-block:: python :linenos: - :emphasize-lines: 2 + :emphasize-lines: 3 @view_config(route_name='add_page', renderer='templates/edit.pt', permission='edit') -- cgit v1.2.3 From 38669d5403206693625ec3d09944d3c7b4eb6ce6 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Feb 2013 01:50:27 +0200 Subject: provide .INI highlighting --- docs/narr/project.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 214440328..a9072e3bf 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -305,7 +305,9 @@ If you want to restrict access such that only a browser running on the same machine as Pyramid will be able to access your Pyramid application, edit the ``development.ini`` file, and replace the ``host`` value in the ``[server:main]`` section. Change it from ``0.0.0.0`` to ``127.0.0.1``. For -example:: +example: + +.. code-block:: ini [server:main] use = egg:waitress#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') 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 70b951b47c31af883aa7a6a5853d9265db7f6fdb Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 17:06:04 +0200 Subject: improve readability --- docs/narr/environment.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index fb3c3d7e3..1ac59bfb6 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -666,9 +666,9 @@ Here's how: def includeme(config): settings = config.registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - -- In the runtime code that you need to access the new settings value, find - the value in the ``registry.settings`` dictionary and use it. In + +- In the runtime code from where you need to access the new settings value, + find the value in the ``registry.settings`` dictionary and use it. In :term:`view` code (or any other code that has access to the request), the easiest way to do this is via ``request.registry.settings``. For example: -- cgit v1.2.3 From 5e63681b1ee7da70e3249509f639b04701e76669 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 21:32:36 +0200 Subject: better to use a cross-reference --- docs/narr/logging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4d1d051d..36f41562a 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -22,8 +22,8 @@ Logging Configuration --------------------- A :app:`Pyramid` project created from a :term:`scaffold` is configured to -allow you to send messages to `Python standard library logging package -`_ loggers from within your +allow you to send messages to :mod:`Python standard library logging package +` loggers from within your application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use a scaffold include a basic configuration for the Python :mod:`logging` package. -- cgit v1.2.3 From 255cba2fde47f54ceae6ddf65174a6c02f308a16 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 13:11:20 +0200 Subject: uncapitalize --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 8ebdfe219..cc443eb25 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -353,7 +353,7 @@ Exception views can be configured with any view registration mechanism: .. _http_redirect: -Using a View Callable to Do an HTTP Redirect +Using a View Callable to do an HTTP Redirect -------------------------------------------- You can issue an HTTP redirect by using the -- cgit v1.2.3 From c0f9371e351431ff6f4eb25a60028cad987efb27 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 17:02:55 +0200 Subject: this has since been fixed --- docs/whatsnew-1.3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index f32053202..a4f259592 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -492,7 +492,7 @@ Known Issues develop`` on Python 3.2, it will quit with an installation error while trying to install ``Pygments``. If this happens, please just rerun the ``setup.py develop`` command again, and it will complete successfully. - This is due to a minor bug in SQLAlchemy 0.7.5 under Python 3, and will be + This is due to a minor bug in SQLAlchemy 0.7.5 under Python 3, and has been fixed in a later SQLAlchemy release. Keep an eye on http://www.sqlalchemy.org/trac/ticket/2421 -- cgit v1.2.3 From 55d81bb135834ec1c2b89860398d5b864ce90cae Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 18:23:06 +0200 Subject: a touch of consistency --- docs/narr/views.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index cc443eb25..6120fa99f 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -524,7 +524,6 @@ The :term:`context` and :term:`request` arguments passed to a view function defined in this style can be defined as follows: context - The :term:`resource` object found via tree :term:`traversal` or :term:`URL dispatch`. -- cgit v1.2.3 From 03e38b7d8cee16292fe58433c5883b7f01908f66 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 18:51:00 +0200 Subject: capitalize --- docs/narr/viewconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index e7c79b09b..792bf31d9 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -38,11 +38,11 @@ A view configuration statement is made about information present in the View configuration is performed in one of two ways: -- by running a :term:`scan` against application source code which has a +- By running a :term:`scan` against application source code which has a :class:`pyramid.view.view_config` decorator attached to a Python object as per :ref:`mapping_views_using_a_decorator_section`. -- by using the :meth:`pyramid.config.Configurator.add_view` method as per +- By using the :meth:`pyramid.config.Configurator.add_view` method as per :ref:`mapping_views_using_imperative_config_section`. .. index:: -- cgit v1.2.3 From 5d3e517aab23d7d40c6ee147ad0395855e337451 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 26 Feb 2013 22:39:54 +0200 Subject: remove a distraction --- docs/narr/urldispatch.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 2a7adea81..1ae7abcbc 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -875,8 +875,7 @@ which you started the application from. For example: .. code-block:: text :linenos: - [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \ - bin/pserve development.ini + $ PYRAMID_DEBUG_ROUTEMATCH=true bin/pserve development.ini Starting server in PID 13586. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 2010-12-16 14:45:19,956 no route matched for url \ -- 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') 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 36e9bf1c488122a1f3ad5bd392be6060009a2eac Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 7 Mar 2013 03:37:01 -0800 Subject: Grammar fixes. Align code in docs with that in the src directory. --- docs/tutorials/wiki/authorization.rst | 46 ++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index ff1e283ab..460a852e0 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -144,7 +144,7 @@ machinery represented by this policy: it is required. The ``callback`` is the Add permission declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Open ``tutorial/views.py``. Add a ``permission='edit'`` parameter +Open ``tutorial/tutorial/views.py``. Add a ``permission='edit'`` parameter to the ``@view_config`` decorator for ``add_page()`` and ``edit_page()``, for example: @@ -152,10 +152,12 @@ to the ``@view_config`` decorator for ``add_page()`` and :linenos: :emphasize-lines: 3 - @view_config(route_name='add_page', renderer='templates/edit.pt', - permission='edit') + @view_config(name='add_page', context='.models.Wiki', + renderer='templates/edit.pt', + permission='edit') -(Only the highlighted line needs to be added.) +(Only the highlighted line, along with its preceding comma, +needs to be added.) The result is that only users who possess the ``edit`` permission at the time of the request may invoke those two views. @@ -167,10 +169,11 @@ decorator for ``view_wiki()`` and ``view_page()``, like this: :linenos: :emphasize-lines: 2 - @view_config(route_name='view_page', renderer='templates/view.pt', + @view_config(context='.models.Page', renderer='templates/view.pt', permission='view') -(Only the highlighted line needs to be added.) +(Only the highlighted line, along with its preceding comma, +needs to be added.) This allows anyone to invoke these two views. @@ -199,7 +202,8 @@ head of ``tutorial/tutorial/views.py``: :emphasize-lines: 3,6-9,11 :language: python -(Only the highlighted lines need to be added.) +(Only the highlighted lines, with other necessary modifications, +need to be added.) :meth:`~pyramid.view.forbidden_view_config` will be used to customize the default 403 Forbidden page. @@ -214,16 +218,16 @@ Now add the ``login`` and ``logout`` views: :linenos: :language: python -``login()`` is decorated with two decorators: +``login()`` has two decorators: - a ``@view_config`` decorator which associates it with the ``login`` route and makes it visible when we visit ``/login``, - a ``@forbidden_view_config`` decorator which turns it into - an :term:`forbidden view`. ``login()`` will be invoked - when a users tries to execute a view callable that - they are not allowed to. For example, if a user has not logged in - and tries to add or edit a Wiki page, he will be shown the - login form before being allowed to continue on. + a :term:`forbidden view`. ``login()`` will be invoked + when a user tries to execute a view callable for which they lack + authorization. For example, if a user has not logged in + and tries to add or edit a Wiki page, they will be shown the + login form before being allowed to continue. The order of these two :term:`view configuration` decorators is unimportant. @@ -241,8 +245,8 @@ content: .. literalinclude:: src/authorization/tutorial/templates/login.pt :language: xml -The above template is referred to within the login view we just -added to ``views.py``. +The above template is referred in the login view that we just added +in ``views.py``. Return a logged_in flag to the renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -256,7 +260,8 @@ Add the following line to the import at the head of :emphasize-lines: 4 :language: python -(Only the highlighted line needs to be added.) +(Only the highlighted line and a trailing comma on the preceding +line need to be added.) Add a ``logged_in`` parameter to the return value of ``view_page()``, ``edit_page()`` and ``add_page()``, @@ -271,11 +276,12 @@ like this: edit_url = edit_url, logged_in = authenticated_userid(request)) -(Only the highlighted line needs to be added.) +(Only the highlighted line and a trailing comma on the preceding +line need to be added.) -:meth:`~pyramid.security.authenticated_userid()` will return None -if the user is not authenticated, or some user id it the user -is authenticated. +:meth:`~pyramid.security.authenticated_userid()` will return ``None`` +if the user is not authenticated, or a user id if the user is +authenticated. Add a "Logout" link when logged in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 136a1ec15e9f9558b87a35ec0274b56793119019 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 8 Mar 2013 01:08:21 +0200 Subject: 2.5 no longer supported --- docs/narr/viewconfig.rst | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index e7c79b09b..9f3b91c26 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -583,8 +583,7 @@ If your view callable is a function, it may be used as a function decorator: return Response('edited!') If your view callable is a class, the decorator can also be used as a class -decorator in Python 2.6 and better (Python 2.5 and below do not support class -decorators). All the arguments to the decorator are the same when applied +decorator. All the arguments to the decorator are the same when applied against a class as when they are applied against a function. For example: .. code-block:: python @@ -601,25 +600,6 @@ against a class as when they are applied against a function. For example: def __call__(self): return Response('hello') -You can use the :class:`~pyramid.view.view_config` decorator as a simple -callable to manually decorate classes in Python 2.5 and below without the -decorator syntactic sugar, if you wish: - -.. code-block:: python - :linenos: - - from pyramid.response import Response - from pyramid.view import view_config - - class MyView(object): - def __init__(self, request): - self.request = request - - def __call__(self): - return Response('hello') - - my_view = view_config(route_name='hello')(MyView) - More than one :class:`~pyramid.view.view_config` decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example: -- cgit v1.2.3 From 2f4bdefd18073c418ae95fe9e5a8c7b2a9d1130e Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Mar 2013 03:06:17 +0200 Subject: capitalize; add term role --- docs/glossary.rst | 4 ++-- docs/narr/assets.rst | 2 +- docs/narr/hooks.rst | 14 +++++++------- docs/narr/traversal.rst | 2 +- docs/narr/urldispatch.rst | 8 ++++---- docs/whatsnew-1.3.rst | 2 +- 6 files changed, 16 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 9220e6b5f..154fb16d6 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -618,13 +618,13 @@ Glossary :term:`configuration decoration` and a :term:`scan` to configure your Pyramid application. - Not Found view + Not Found View An :term:`exception view` invoked by :app:`Pyramid` when the developer explicitly raises a :class:`pyramid.httpexceptions.HTTPNotFound` exception from within :term:`view` code or :term:`root factory` code, or when the current request doesn't match any :term:`view configuration`. :app:`Pyramid` provides a default implementation of a - not found view; it can be overridden. See + Not Found View; it can be overridden. See :ref:`changing_the_notfound_view`. Forbidden view diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 7b620548d..deaf0ce08 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -323,7 +323,7 @@ its behavior is almost exactly the same once it's configured. ``add_view`` (at least those without a ``route_name``). A :class:`~pyramid.static.static_view` static view cannot be made root-relative when you use traversal unless it's registered as a - :term:`Not Found view`. + :term:`Not Found View`. To serve files within a directory located on your filesystem at ``/path/to/static/dir`` as the result of a "catchall" route hanging from the diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index f38d57e73..d7af5ab98 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -19,7 +19,7 @@ found view`, which is a :term:`view callable`. The default Not Found View can be overridden through application configuration. If your application uses :term:`imperative configuration`, you can replace -the Not Found view by using the +the Not Found View by using the :meth:`pyramid.config.Configurator.add_notfound_view` method: .. code-block:: python @@ -29,7 +29,7 @@ the Not Found view by using the config.add_notfound_view(notfound) Replace ``helloworld.views.notfound`` with a reference to the :term:`view -callable` you want to use to represent the Not Found view. The :term:`not +callable` you want to use to represent the Not Found View. The :term:`not found view` callable is a view callable like any other. If your application instead uses :class:`pyramid.view.view_config` decorators @@ -51,12 +51,12 @@ and a :term:`scan`, you can replace the Not Found view by using the This does exactly what the imperative example above showed. -Your application can define *multiple* not found views if necessary. Both +Your application can define *multiple* Not Found Views if necessary. Both :meth:`pyramid.config.Configurator.add_notfound_view` and :class:`pyramid.view.notfound_view_config` take most of the same arguments as :class:`pyramid.config.Configurator.add_view` and -:class:`pyramid.view.view_config`, respectively. This means that not found -views can carry predicates limiting their applicability. For example: +:class:`pyramid.view.view_config`, respectively. This means that Not Found +Views can carry predicates limiting their applicability. For example: .. code-block:: python :linenos: @@ -106,8 +106,8 @@ Here's some sample code that implements a minimal NotFound view callable: When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that - caused the not found view to be called. The value of - ``request.exception.message`` will be a value explaining why the not found + caused the Not Found View to be called. The value of + ``request.exception.message`` will be a value explaining why the Not Found error was raised. This message will be different when the ``pyramid.debug_notfound`` environment setting is true than it is when it is false. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 8e7f93a1b..1234620c2 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -389,7 +389,7 @@ Using the :term:`view name` (``baz``) and the type, view lookup asks the Let's say that view lookup finds no matching view type. In this circumstance, the :app:`Pyramid` :term:`router` returns the result of the -:term:`not found view` and the request ends. +:term:`Not Found View` and the request ends. However, for this tree: diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 2a7adea81..16af4d088 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -814,7 +814,7 @@ bro." body. If a request enters the application with the ``PATH_INFO`` value of ``/has_slash/``, the second route will match. If a request enters the application with the ``PATH_INFO`` value of ``/has_slash``, a route *will* be -found by the slash-appending not found view. An HTTP redirect to +found by the slash-appending :term:`Not Found View`. An HTTP redirect to ``/has_slash/`` will be returned to the user's browser. As a result, the ``notfound`` view will never actually be called. @@ -849,12 +849,12 @@ exactly the same job: .. warning:: You **should not** rely on this mechanism to redirect ``POST`` requests. - The redirect of the slash-appending not found view will turn a ``POST`` - request into a ``GET``, losing any ``POST`` data in the original + The redirect of the slash-appending :term:`Not Found View` will turn a + ``POST`` request into a ``GET``, losing any ``POST`` data in the original request. See :ref:`view_module` and :ref:`changing_the_notfound_view` for a more -general description of how to configure a view and/or a not found view. +general description of how to configure a view and/or a :term:`Not Found View`. .. index:: pair: debugging; route matching diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index f32053202..a73e2969d 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -212,7 +212,7 @@ Not Found helpers: - New API: :meth:`pyramid.config.Configurator.add_notfound_view`. This is a wrapper for :meth:`pyramid.Config.configurator.add_view` which provides support for an "append_slash" feature as well as doing the right thing when - it comes to permissions (a not found view should always be public). It + it comes to permissions (a Not Found View should always be public). It should be preferred over calling ``add_view`` directly with ``context=HTTPNotFound`` as was previously recommended. -- cgit v1.2.3 From cec2b05e74b3296ab8b54b9644223e08f269808b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Mar 2013 03:15:15 +0200 Subject: consistency --- docs/narr/hooks.rst | 9 +++++---- docs/narr/viewconfig.rst | 2 +- docs/whatsnew-1.4.rst | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index d7af5ab98..d103ca1cd 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -79,7 +79,7 @@ The ``notfound_get`` view will be called when a view could not be found and the request method was ``GET``. The ``notfound_post`` view will be called when a view could not be found and the request method was ``POST``. -Like any other view, the notfound view must accept at least a ``request`` +Like any other view, the Not Found View must accept at least a ``request`` parameter, or both ``context`` and ``request``. The ``request`` is the current :term:`request` representing the denied action. The ``context`` (if used in the call signature) will be the instance of the @@ -91,7 +91,8 @@ Both :meth:`pyramid.config.Configurator.add_notfound_view` and redirect requests to slash-appended routes. See :ref:`redirecting_to_slash_appended_routes` for examples. -Here's some sample code that implements a minimal NotFound view callable: +Here's some sample code that implements a minimal :term:`Not Found View` +callable: .. code-block:: python :linenos: @@ -103,7 +104,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. note:: - When a NotFound view callable is invoked, it is passed a + When a Not Found View callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the Not Found View to be called. The value of @@ -122,7 +123,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. warning:: - When a NotFound view callable accepts an argument list as + When a Not Found View callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception instance. If diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 9f3b91c26..96c0b88cf 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -81,7 +81,7 @@ invoked. If no view can be found with predicates which allow it to be matched up with the request, :app:`Pyramid` will return an error to the user's browser, representing a "not found" (404) page. See :ref:`changing_the_notfound_view` -for more information about changing the default notfound view. +for more information about changing the default :term:`Not Found View`. Other view configuration arguments are non-predicate arguments. These tend to modify the response of the view callable or prevent the view callable from diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 34fda5f37..f725615f3 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -108,7 +108,7 @@ Minor Feature Additions - The static view machinery now raises rather than returns :class:`pyramid.httpexceptions.HTTPNotFound` and :class:`pyramid.httpexceptions.HTTPMovedPermanently` exceptions, so these can - be caught by the notfound view (and other exception views). + be caught by the Not Found View (and other exception views). - When there is a predicate mismatch exception (seen when no view matches for a given request due to predicates not working), the exception now contains -- cgit v1.2.3 From 291c31c09edfbc09346ae985a865dd13cab7987b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Mar 2013 16:28:27 +0200 Subject: grammar --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 3a94b4f7d..be9ab8d03 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -80,7 +80,7 @@ policy. You must also enable an :term:`authentication policy` in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the -:meth:`~pyramid.config.Configurator.set_authentication_policy` and method +:meth:`~pyramid.config.Configurator.set_authentication_policy` method during application setup to specify the authentication policy. For example: -- cgit v1.2.3 From 416c38fc034ff55e70d72593493327ac44c280a9 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 10 Mar 2013 09:40:58 +0200 Subject: change awkward sentence --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 3a94b4f7d..a6c9c196b 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -65,7 +65,7 @@ policies. Enabling an Authorization Policy -------------------------------- -By default, :app:`Pyramid` enables no authorization policy. All +:app:`Pyramid` does not enable any authorization policy by default. All views are accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to enable an authorization policy. -- cgit v1.2.3 From fcd48d5d33421f806080df00e29501c4a0fd1476 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 10 Mar 2013 09:47:18 +0200 Subject: capitalize --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 3a94b4f7d..ede4b6749 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -98,7 +98,7 @@ For example: config.set_authentication_policy(authn_policy) config.set_authorization_policy(authz_policy) -.. note:: the ``authentication_policy`` and ``authorization_policy`` +.. note:: The ``authentication_policy`` and ``authorization_policy`` arguments may also be passed to their respective methods mentioned above as :term:`dotted Python name` values, each representing the dotted name path to a suitable implementation global defined at Python module scope. -- cgit v1.2.3 From 07bd8622f4c5ec3340630e977e202991b67d59d8 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 12 Mar 2013 01:24:18 +0200 Subject: a warning is overkill --- docs/narr/introspector.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 7784e8960..dec22c5b1 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -7,6 +7,8 @@ Pyramid Configuration Introspection =================================== +.. versionadded:: 1.3 + When Pyramid starts up, each call to a :term:`configuration directive` causes one or more :term:`introspectable` objects to be registered with an :term:`introspector`. The introspector can be queried by application code to @@ -15,10 +17,6 @@ feature is useful for debug toolbars, command-line scripts which show some aspect of configuration, and for runtime reporting of startup-time configuration settings. -.. warning:: - - Introspection is new in Pyramid 1.3. - Using the Introspector ---------------------- -- cgit v1.2.3 From 18d0a34fbd804be11046efe7f10b7212f018091b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 12 Mar 2013 19:55:09 +0200 Subject: fix markup --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index ba43f3ea6..434e2bd6c 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article,`"A Whirlwind Tour of Advanced +For more information, see the article, `"A Whirlwind Tour of Advanced Configuration Tactics" `_, in the Pyramid Cookbook. -- cgit v1.2.3 From 72f88a80d6b8a7ea758e8ba03d55fa622ff98bbe Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 12 Mar 2013 21:12:09 +0200 Subject: use a Sphinx ref instead of raw url Other than reducing ugliness, when building the doc with Python 3, the target is a Python 3 version of the class; same applies to Python 2. --- docs/narr/threadlocals.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst index 909f643a0..5ff70565c 100644 --- a/docs/narr/threadlocals.rst +++ b/docs/narr/threadlocals.rst @@ -62,8 +62,7 @@ Because one :app:`Pyramid` application is permitted to call (perhaps as a :term:`WSGI` app with help from the :func:`pyramid.wsgi.wsgiapp2` decorator), these variables are managed in a *stack* during normal system operations. The stack -instance itself is a `threading.local -`_. +instance itself is a :class:`threading.local`. During normal operations, the thread locals stack is managed by a :term:`Router` object. At the beginning of a request, the Router -- cgit v1.2.3 From 2dfdecd4c7a8255702aa08f2807b4a3341b270f7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 12 Mar 2013 22:40:08 +0200 Subject: fix whitespace issue... remove tabs --- docs/narr/views.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 077d27366..90f6825c0 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -537,41 +537,41 @@ The following types work as view callables in this style: e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - def view(context, request): - return Response('OK') + def view(context, request): + return Response('OK') #. Classes that have an ``__init__`` method that accepts ``context, request`` and a ``__call__`` method which accepts no arguments, e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class view(object): - def __init__(self, context, request): - self.context = context - self.request = request + class view(object): + def __init__(self, context, request): + self.context = context + self.request = request - def __call__(self): - return Response('OK') + def __call__(self): + return Response('OK') #. Arbitrary callables that have a ``__call__`` method that accepts ``context, request``, e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class View(object): - def __call__(self, context, request): - return Response('OK') - view = View() # this is the view callable + class View(object): + def __call__(self, context, request): + return Response('OK') + view = View() # this is the view callable This style of calling convention is most useful for :term:`traversal` based applications, where the context object is frequently used within the view -- 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/conventions.rst | 12 +++-- docs/glossary.rst | 4 ++ docs/narr/commandline.rst | 28 +++++----- docs/narr/environment.rst | 2 +- docs/narr/extending.rst | 4 +- docs/narr/firstapp.rst | 4 +- docs/narr/i18n.rst | 13 +++-- docs/narr/install.rst | 65 ++++++++++++----------- docs/narr/project.rst | 30 +++++------ docs/narr/security.rst | 2 +- docs/narr/templates.rst | 2 +- docs/narr/upgrading.rst | 2 +- docs/narr/urldispatch.rst | 2 +- docs/tutorials/bfg/index.rst | 6 +-- docs/tutorials/modwsgi/index.rst | 6 +-- docs/tutorials/wiki/NOTE-relocatable.txt | 2 +- docs/tutorials/wiki/distributing.rst | 4 +- docs/tutorials/wiki/installation.rst | 24 ++++----- docs/tutorials/wiki/tests.rst | 8 +-- docs/tutorials/wiki2/definingviews.rst | 4 +- docs/tutorials/wiki2/distributing.rst | 4 +- docs/tutorials/wiki2/installation.rst | 28 +++++----- docs/tutorials/wiki2/src/authorization/README.txt | 6 +-- docs/tutorials/wiki2/src/basiclayout/README.txt | 6 +-- docs/tutorials/wiki2/src/models/README.txt | 6 +-- docs/tutorials/wiki2/src/tests/README.txt | 6 +-- docs/tutorials/wiki2/src/views/README.txt | 6 +-- docs/tutorials/wiki2/tests.rst | 8 +-- docs/whatsnew-1.1.rst | 5 +- docs/whatsnew-1.3.rst | 8 +-- 30 files changed, 158 insertions(+), 149 deletions(-) (limited to 'docs') diff --git a/docs/conventions.rst b/docs/conventions.rst index 0c38e11d8..4cffd1084 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -55,21 +55,25 @@ character, e.g.: .. code-block:: text - $ ../bin/nosetests + $ $VENV/bin/nosetests + +(See :term:`virtualenv` for the meaning of ``$VENV``) Example blocks representing Windows ``cmd.exe`` commands are prefixed with a drive letter and/or a directory name, e.g.: .. code-block:: text - c:\examples> ..\Scripts\nosetests + c:\examples> %VENV%\Scripts\nosetests + +(See :term:`virtualenv` for the meaning of ``%VENV%``) Sometimes, when it's unknown which directory is current, Windows ``cmd.exe`` example block commands are prefixed only with a ``>`` character, e.g.: .. code-block:: text - > ..\Scripts\nosetests + > %VENV%\Scripts\nosetests When a command that should be typed on one line is too long to fit on a page, the backslash ``\`` is used to indicate that the following printed line @@ -77,7 +81,7 @@ should actually be part of the command: .. code-block:: text - c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ + c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ --cover-erase --with-coverage A sidebar, which presents a concept tangentially related to content diff --git a/docs/glossary.rst b/docs/glossary.rst index 711994426..ccff2d7db 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -150,6 +150,10 @@ Glossary or `the leading tool `_ that allows one to create such environments. + Note: whenever you encounter commands prefixed with ``$VENV`` (Unix) + or ``%VENV`` (Windows), know that that is the environment variable whose + value is the root of the virtual environment in question. + resource An object representing a node in the :term:`resource tree` of an application. If :mod:`traversal` is used, a resource is an element in 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 diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 35bfddb8d..e059acc4e 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -546,7 +546,7 @@ for settings documented as such. For example, you might start your .. code-block:: text $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \ - bin/pserve MyProject.ini + $VENV/bin/pserve MyProject.ini If you started your application this way, your :app:`Pyramid` application would behave in the same manner as if you had placed the diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index dd9281c73..beece7640 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -200,8 +200,8 @@ like this: overridden elements, such as templates and static assets as necessary. - Install the new package into the same Python environment as the original - application (e.g. ``$myvenv/bin/python setup.py develop`` or - ``$myvenv/bin/python setup.py install``). + application (e.g. ``$VENV/bin/python setup.py develop`` or + ``$VENV/bin/python setup.py install``). - Change the ``main`` function in the new package's ``__init__.py`` to include the original :app:`Pyramid` application's configuration functions via diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index ab6a46c2f..6d3786d8e 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -29,13 +29,13 @@ On UNIX: .. code-block:: text - $ /path/to/your/virtualenv/bin/python helloworld.py + $ $VENV/bin/python helloworld.py On Windows: .. code-block:: text - C:\> \path\to\your\virtualenv\Scripts\python.exe helloworld.py + C:\> %VENV%\Scripts\python.exe helloworld.py This command will not return and nothing will be printed to the console. When port 8080 is visited by a browser on the URL ``/hello/world``, the diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 24cd3ff54..74765f8e2 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -276,7 +276,7 @@ like so: .. code-block:: text $ cd /my/virtualenv - $ bin/easy_install Babel lingua + $ $VENV/bin/easy_install Babel lingua Installation on Windows +++++++++++++++++++++++ @@ -287,8 +287,7 @@ like so: .. code-block:: text - C> cd \my\virtualenv - C> Scripts\easy_install Babel lingua + C> %VENV%\Scripts\easy_install Babel lingua .. index:: single: Babel; message extractors @@ -347,7 +346,7 @@ extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $myvenv/bin/python setup.py extract_messages + $ $VENV/bin/python setup.py extract_messages The message catalog ``.pot`` template will end up in: @@ -439,7 +438,7 @@ init_catalog`` command: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py init_catalog -l es + $ $VENV/bin/python setup.py init_catalog -l es By default, the message catalog ``.po`` file will end up in: @@ -471,7 +470,7 @@ Then use the ``setup.py update_catalog`` command. .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py update_catalog + $ $VENV/bin/python setup.py update_catalog .. index:: pair: compiling; message catalog @@ -487,7 +486,7 @@ translations, compile ``.po`` files to ``.mo`` files: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py compile_catalog + $ $VENV/bin/python setup.py compile_catalog This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 85dfd5bf4..6656882c9 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -264,16 +264,21 @@ as your system's administrative user. For example: Creating the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once the :term:`virtualenv` package is installed in your Python, you -can then create a virtual environment. To do so, invoke the -following: +Once the :term:`virtualenv` package is installed in your Python environment, +you can then create a virtual environment. To do so, invoke the following: .. code-block:: text - $ virtualenv --no-site-packages env - New python executable in env/bin/python + $ export $VENV=~/env + $ virtualenv --no-site-packages $VENV + New python executable in /home/foo/env/bin/python Installing setuptools.............done. +You can either follow the use of the environment variable, ``$VENV``, +or replace it with the root directory of the :term:`virtualenv`. +In that case, the `export` command can be skipped. +If you choose the former approach, ensure that it's an absolute path. + .. warning:: Using ``--no-site-packages`` when generating your @@ -289,20 +294,16 @@ following: ``virtualenv`` script. It's perfectly acceptable (and desirable) to create a virtualenv as a normal user. -You should perform any following commands that mention a "bin" -directory from within the ``env`` virtualenv dir. Installing :app:`Pyramid` Into the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After you've got your ``env`` virtualenv installed, you may install -:app:`Pyramid` itself using the following commands from within the -virtualenv (``env``) directory you created in the last step. +After you've got your virtualenv installed, you may install +:app:`Pyramid` itself using the following commands: .. code-block:: text - $ cd env - $ bin/easy_install pyramid + $ $VENV/bin/easy_install pyramid The ``easy_install`` command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies. @@ -339,25 +340,25 @@ Windows Using Python 2 c:\> c:\Python27\python ez_setup.py -#. Use that Python's `bin/easy_install` to install `virtualenv`: +#. Install `virtualenv`: .. code-block:: text c:\> c:\Python27\Scripts\easy_install virtualenv -#. Use that Python's virtualenv to make a workspace: +#. Make a :term:`virtualenv` workspace: .. code-block:: text - c:\> c:\Python27\Scripts\virtualenv --no-site-packages env - -#. Switch to the ``env`` directory: - - .. code-block:: text + c:\> set VENV=c:\env + c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV% - c:\> cd env + You can either follow the use of the environment variable, ``%VENV%``, + or replace it with the root directory of the :term:`virtualenv`. + In that case, the `set` command can be skipped. + If you choose the former approach, ensure that it's an absolute path. -#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell +#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell environment wired to use the virtualenv. #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies @@ -365,7 +366,7 @@ Windows Using Python 2 .. code-block:: text - c:\env> Scripts\easy_install pyramid + c:\env> %VENV%\Scripts\easy_install pyramid Windows Using Python 3 ~~~~~~~~~~~~~~~~~~~~~~ @@ -388,25 +389,25 @@ Windows Using Python 3 c:\> c:\Python32\python distribute_setup.py -#. Use that Python's `bin/easy_install` to install `virtualenv`: +#. Install :term:`virtualenv`: .. code-block:: text c:\> c:\Python32\Scripts\easy_install virtualenv -#. Use that Python's virtualenv to make a workspace: +#. Make a :term:`virtualenv` workspace: .. code-block:: text - c:\> c:\Python32\Scripts\virtualenv --no-site-packages env - -#. Switch to the ``env`` directory: - - .. code-block:: text + c:\> set VENV=c:\env + c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% - c:\> cd env + You can either follow the use of the environment variable, ``%VENV%``, + or replace it with the root directory of the :term:`virtualenv`. + In that case, the `set` command can be skipped. + If you choose the former approach, ensure that it's an absolute path. -#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell +#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell environment wired to use the virtualenv. #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies @@ -414,7 +415,7 @@ Windows Using Python 3 .. code-block:: text - c:\env> Scripts\easy_install pyramid + c:\env> %VEN%\Scripts\easy_install pyramid What Gets Installed ------------------- diff --git a/docs/narr/project.rst b/docs/narr/project.rst index a9072e3bf..a168c24eb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -80,13 +80,13 @@ On UNIX: .. code-block:: text - $ bin/pcreate -s starter MyProject + $ $VENV/bin/pcreate -s starter MyProject Or on Windows: .. code-block:: text - > Scripts\pcreate -s starter MyProject + > %VENV%\Scripts\pcreate -s starter MyProject The above command uses the ``pcreate`` command to create a project with the ``starter`` scaffold. To use a different scaffold, such as @@ -95,20 +95,20 @@ on UNIX: .. code-block:: text - $ bin/pcreate -s alchemy MyProject + $ $VENV/bin/pcreate -s alchemy MyProject Or on Windows: .. code-block:: text - > Scripts\pcreate -s alchemy MyProject + > %VENV%\Scripts\pcreate -s alchemy MyProject Here's sample output from a run of ``pcreate`` on UNIX for a project we name ``MyProject``: .. code-block:: text - $ bin/pcreate -s starter MyProject + $ $VENV/bin/pcreate -s starter MyProject Creating template pyramid Creating directory ./MyProject # ... more output ... @@ -177,21 +177,21 @@ On UNIX: .. code-block:: text $ cd MyProject - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop Or on Windows: .. code-block:: text > cd MyProject - > ..\Scripts\python.exe setup.py develop + > %VENV%\Scripts\python.exe setup.py develop Elided output from a run of this command on UNIX is shown below: .. code-block:: text $ cd MyProject - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop ... Finished processing dependencies for MyProject==0.0 @@ -216,19 +216,19 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q Or on Windows: .. code-block:: text - > ..\Scripts\python.exe setup.py test -q + > %VENV%\Scripts\python.exe setup.py test -q Here's sample output from a test run on UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q running test running egg_info writing requirements to MyProject.egg-info/requires.txt @@ -272,19 +272,19 @@ On UNIX: .. code-block:: text - $ ../bin/pserve development.ini + $ $VENV/bin/pserve development.ini On Windows: .. code-block:: text - > ..\Scripts\pserve development.ini + > %VENV%\Scripts\pserve development.ini Here's sample output from a run of ``pserve`` on UNIX: .. code-block:: text - $ ../bin/pserve development.ini + $ $VENV/bin/pserve development.ini Starting server in PID 16601. serving on http://0.0.0.0:6543 @@ -359,7 +359,7 @@ For example, on UNIX: .. code-block:: text - $ ../bin/pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload Starting subprocess with file monitor Starting server in PID 16601. serving on http://0.0.0.0:6543 diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 5a1a92e08..5b79edd19 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -507,7 +507,7 @@ example: .. code-block:: text - $ PYRAMID_DEBUG_AUTHORIZATION=1 bin/pserve myproject.ini + $ PYRAMID_DEBUG_AUTHORIZATION=1 $VENV/bin/pserve myproject.ini When any authorization takes place during a top-level view rendering, a message will be logged to the console (to stderr) about what ACE in diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 08fa9883e..1f1c07027 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -771,7 +771,7 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini + $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.reload_templates`` key to ``true`` within the diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index 20487b448..ca6dc565b 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -183,7 +183,7 @@ server run with the ``PYTHONWARNINGS`` environment variable set to .. code-block:: bash - $ PYTHONWARNINGS=default bin/pserve development.ini + $ PYTHONWARNINGS=default $VENV/bin/pserve development.ini On Windows, you need to issue two commands: diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index a327e937b..181b07259 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -875,7 +875,7 @@ which you started the application from. For example: .. code-block:: text :linenos: - $ PYRAMID_DEBUG_ROUTEMATCH=true bin/pserve development.ini + $ PYRAMID_DEBUG_ROUTEMATCH=true $VENV/bin/pserve development.ini Starting server in PID 13586. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 2010-12-16 14:45:19,956 no route matched for url \ diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst index e68e63b0b..a50637279 100644 --- a/docs/tutorials/bfg/index.rst +++ b/docs/tutorials/bfg/index.rst @@ -47,7 +47,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a .. code-block:: bash - $ bfgenv/bin/python setup.py test + $ $VENV/bin/python setup.py test ``bfgenv`` above will be the virtualenv into which you've installed :mod:`repoze.bfg` 1.3. @@ -62,7 +62,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a $ cd ~ $ virtualenv --no-site-packages pyramidenv $ cd pyramidenv - $ bin/easy_install pyramid + $ $VENV/bin/easy_install pyramid #. Put a *copy* of your :mod:`repoze.bfg` application into a temporary location (perhaps by checking a fresh copy of the application out @@ -186,7 +186,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a .. code-block:: bash $ cd /tmp/bfgapp - $ ~/pyramidenv/bin/python setup.py test + $ $VENV/bin/python setup.py test #. Fix any test failures. diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index a22f12610..e0021f8db 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -53,7 +53,7 @@ specific path information for commands and files. .. code-block:: text $ cd ~/modwsgi/env - $ bin/easy_install pyramid + $ $VENV/bin/easy_install pyramid #. Create and install your :app:`Pyramid` application. For the purposes of this tutorial, we'll just be using the ``pyramid_starter`` application as @@ -63,9 +63,9 @@ specific path information for commands and files. .. code-block:: text $ cd ~/modwsgi/env - $ bin/pcreate -s starter myapp + $ $VENV/bin/pcreate -s starter myapp $ cd myapp - $ ../bin/python setup.py install + $ $VENV/bin/python setup.py install #. Within the virtualenv directory (``~/modwsgi/env``), create a script named ``pyramid.wsgi``. Give it these contents: diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt index 4c778ad04..e942caba8 100644 --- a/docs/tutorials/wiki/NOTE-relocatable.txt +++ b/docs/tutorials/wiki/NOTE-relocatable.txt @@ -1,5 +1,5 @@ We specifically use relative package references where possible so this demo -works even if the user names their package (in the 'bin/pcreate -s +works even if the user names their package (in the '$VENV/bin/pcreate -s zodb ...' step) something other than 'tutorial'. Specifically: diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst index ed0af222f..9c63cf0bd 100644 --- a/docs/tutorials/wiki/distributing.rst +++ b/docs/tutorials/wiki/distributing.rst @@ -12,13 +12,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py sdist + $ $VENV/bin/python setup.py sdist On Windows: .. code-block:: text - c:\pyramidtut> ..\Scripts\python setup.py sdist + c:\pyramidtut> %VENV%\Scripts\python setup.py sdist The output of such a command will be something like: diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index b545cdba0..b51254b92 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -22,7 +22,7 @@ Preparation, UNIX .. code-block:: text - $ bin/easy_install docutils pyramid_tm pyramid_zodbconn \ + $ $VENV/bin/easy_install docutils pyramid_tm pyramid_zodbconn \ pyramid_debugtoolbar nose coverage Preparation, Windows @@ -39,7 +39,7 @@ Preparation, Windows .. code-block:: text - c:\pyramidtut> Scripts\easy_install docutils pyramid_tm \ + c:\pyramidtut> %VENV%\Scripts\easy_install docutils pyramid_tm \ pyramid_zodbconn pyramid_debugtoolbar nose coverage .. _making_a_project: @@ -59,13 +59,13 @@ On UNIX: .. code-block:: text - $ bin/pcreate -s zodb tutorial + $ $VENV/bin/pcreate -s zodb tutorial On Windows: .. code-block:: text - c:\pyramidtut> Scripts\pcreate -s zodb tutorial + c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial .. note:: You don't have to call it `tutorial` -- the code uses relative paths for imports and finding templates and static @@ -91,14 +91,14 @@ On UNIX: .. code-block:: text $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text C:\pyramidtut> cd tutorial - C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + C:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop .. _running_tests: @@ -112,13 +112,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q Expose Test Coverage Information ================================ @@ -133,13 +133,13 @@ On UNIX: .. code-block:: text - $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^ + c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial ^ --cover-erase --with-coverage Looks like the code in the ``zodb`` scaffold for ZODB projects is @@ -157,13 +157,13 @@ On UNIX: .. code-block:: text - $ ../bin/pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload + c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload .. note:: diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index 36ae7930b..e40dc286b 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -71,13 +71,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Once that command has completed successfully, we can run the tests themselves: @@ -86,13 +86,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q The expected result looks something like: diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 9d2f8fb7f..5727816c8 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -52,14 +52,14 @@ On UNIX: .. code-block:: text $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text c:\pyramidtut> cd tutorial - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Success executing this command will end with a line to the console something like:: diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst index 96293603c..3b048a141 100644 --- a/docs/tutorials/wiki2/distributing.rst +++ b/docs/tutorials/wiki2/distributing.rst @@ -12,13 +12,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py sdist + $ $VENV/bin/python setup.py sdist On Windows: .. code-block:: text - c:\pyramidtut> ..\Scripts\python setup.py sdist + c:\pyramidtut> %VENV%\Scripts\python setup.py sdist The output of such a command will be something like: diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 9fa01d513..255a60ec2 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -52,13 +52,13 @@ On UNIX: .. code-block:: text - $ bin/pcreate -s alchemy tutorial + $ $VENV/bin/pcreate -s alchemy tutorial On Windows: .. code-block:: text - c:\pyramidtut> Scripts\pcreate -s alchemy tutorial + c:\pyramidtut> %VENV%\pcreate -s alchemy tutorial .. note:: If you are using Windows, the ``alchemy`` scaffold may not deal gracefully with installation into a @@ -83,14 +83,14 @@ On UNIX: .. code-block:: text $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text c:\pyramidtut> cd tutorial - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Success executing this command will end with a line to the console something like:: @@ -109,13 +109,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q For a successful test run, you should see output that ends like this:: @@ -141,13 +141,13 @@ On UNIX: .. code-block:: text - $ ../bin/easy_install nose coverage + $ $VENV/bin/easy_install nose coverage On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage + c:\pyramidtut\tutorial> %VENV%\Scripts\easy_install nose coverage Once ``nose`` and ``coverage`` are installed, we can actually run the coverage tests. @@ -156,13 +156,13 @@ On UNIX: .. code-block:: text - $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ + c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ --cover-erase --with-coverage If successful, you will see output something like this:: @@ -200,13 +200,13 @@ On UNIX: .. code-block:: text - $ ../bin/initialize_tutorial_db development.ini + $ $VENV/bin/initialize_tutorial_db development.ini On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini + c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini The output to your console should be something like this:: @@ -248,13 +248,13 @@ On UNIX: .. code-block:: text - $ ../bin/pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload + c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload If successful, you will see something like this on your console:: diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/authorization/README.txt +++ b/docs/tutorials/wiki2/src/authorization/README.txt @@ -6,9 +6,9 @@ Getting Started - cd -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/basiclayout/README.txt +++ b/docs/tutorials/wiki2/src/basiclayout/README.txt @@ -6,9 +6,9 @@ Getting Started - cd -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/models/README.txt +++ b/docs/tutorials/wiki2/src/models/README.txt @@ -6,9 +6,9 @@ Getting Started - cd -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/tests/README.txt +++ b/docs/tutorials/wiki2/src/tests/README.txt @@ -6,9 +6,9 @@ Getting Started - cd -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/views/README.txt +++ b/docs/tutorials/wiki2/src/views/README.txt @@ -6,9 +6,9 @@ Getting Started - cd -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index 7aa3c464d..33b5d35c1 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -66,13 +66,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Once that command has completed successfully, we can run the tests themselves: @@ -81,13 +81,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q The expected result ends something like: diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index 18d0aa0b1..f33fc94ba 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -395,8 +395,9 @@ Deprecations and Behavior Differences when porting your application from an older version of Pyramid. Use the ``PYTHONWARNINGS`` environment variable with the value ``all`` in the shell you use to invoke ``paster serve`` to see these warnings, e.g. on - UNIX, ``PYTHONWARNINGS=all bin/paster serve development.ini``. Python 2.5 - and 2.6 show deprecation warnings by default, so this is unecessary there. + UNIX, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``. + Python 2.5 and 2.6 show deprecation warnings by default, + so this is unecessary there. All deprecation warnings are emitted to the console. - The :class:`pyramid.view.static` class has been deprecated in favor of the diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index d121413e2..ef0256383 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -46,12 +46,12 @@ maintain them ourselves. As a result, we've had to make some changes. Previously (in Pyramid 1.0, 1.1 and 1.2), you created a Pyramid application using ``paster create``, like so:: - $ myvenv/bin/paster create -t pyramid_starter foo + $ $VENV/bin/paster create -t pyramid_starter foo In 1.3, you're now instead required to create an application using ``pcreate`` like so:: - $ myvenv/bin/pcreate -s starter foo + $ $VENV/bin/pcreate -s starter foo ``pcreate`` is required to be used for internal Pyramid scaffolding; externally distributed scaffolding may allow for both ``pcreate`` and/or @@ -59,11 +59,11 @@ externally distributed scaffolding may allow for both ``pcreate`` and/or In previous Pyramid versions, you ran a Pyramid application like so:: - $ myvenv/bin/paster serve development.ini + $ $VENV/bin/paster serve development.ini Instead, you now must use the ``pserve`` command in 1.3:: - $ myvenv/bin/pserve development.ini + $ $VENV/bin/pserve development.ini The ``ini`` configuration file format supported by Pyramid has not changed. As a result, Python 2-only users can install PasteScript manually and use -- cgit v1.2.3 From 919643eec1a480cee442331a966a9c6c90fb0965 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:36:18 +0200 Subject: typo --- docs/narr/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 6656882c9..04a060ac3 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -415,7 +415,7 @@ Windows Using Python 3 .. code-block:: text - c:\env> %VEN%\Scripts\easy_install pyramid + c:\env> %VENV%\Scripts\easy_install pyramid What Gets Installed ------------------- -- cgit v1.2.3 From e81e76ae9e0fd1c45ddb61a873d67cd6e2d9f643 Mon Sep 17 00:00:00 2001 From: Georges Dubus Date: Thu, 14 Mar 2013 10:39:05 +0100 Subject: Added an options argument to pyramid.paste.get_appsettings, just like get_app, that can be used to get the settings when interpolation is used in the config file. --- docs/api/paster.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api/paster.rst b/docs/api/paster.rst index bde128e05..edc3738fc 100644 --- a/docs/api/paster.rst +++ b/docs/api/paster.rst @@ -9,6 +9,6 @@ .. autofunction:: get_app(config_uri, name=None, options=None) - .. autofunction:: get_appsettings(config_uri, name=None) + .. autofunction:: get_appsettings(config_uri, name=None, options=None) .. autofunction:: setup_logging(config_uri) -- cgit v1.2.3 From 44c64f2027a6c32a97d7c52970557f3e1aed9b06 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Mar 2013 15:00:58 +0200 Subject: improve description; fix spelling --- docs/glossary.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index ccff2d7db..40c15efdc 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -403,10 +403,9 @@ Glossary dispatching and other application configuration tasks. reStructuredText - A `plain text format `_ - that is the defacto standard for descriptive text shipped in - :term:`distribution` files, and Python docstrings. This - documentation is authored in ReStructuredText format. + A `plain text markup format `_ + that is the defacto standard for documenting Python projects. + The Pyramid documentation is written in reStructuredText. root The object at which :term:`traversal` begins when :app:`Pyramid` -- cgit v1.2.3 From 286a9ecab57621d0e1af1ba70986ef083149137a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Mar 2013 12:22:35 +0200 Subject: grammar --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 68be4ee7c..86fe97956 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -226,7 +226,7 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` method that takes a two arguments +Our example model has an ``__init__`` method that takes two arguments (``name``, and ``value``). It stores these values as ``self.name`` and ``self.value`` within the ``__init__`` function itself. The ``MyModel`` class also has a -- cgit v1.2.3 From bc063da0e248c9b6df6af29ec1f5217accd703d2 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Mar 2013 13:09:59 +0200 Subject: no need to re-install This will continue working fine. --- docs/tutorials/wiki2/definingmodels.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index bd1cb00d7..99f7969bc 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -77,8 +77,6 @@ following: Installing the Project and re-initializing the Database ------------------------------------------------------- -Redo the steps in :ref:`installing_project_in_dev_mode`. - Because our model has changed, in order to reinitialize the database, we need to rerun the ``initialize_tutorial_db`` command to pick up the changes you've made to both the models.py file and to the initializedb.py file. -- cgit v1.2.3 From f39d8bf14b163e251b5c6eac88f07f862fd007b0 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Mar 2013 14:32:08 +0200 Subject: that should be lower-case --- docs/tutorials/wiki2/definingviews.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 5727816c8..f2ac2f85f 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -126,7 +126,7 @@ The ``view_page`` view function ------------------------------- ``view_page()`` is used to display a single page of our -wiki. It renders the :term:`ReStructuredText` body of a page (stored as +wiki. It renders the :term:`reStructuredText` body of a page (stored as the ``data`` attribute of a ``Page`` model object) as HTML. Then it substitutes an HTML anchor for each *WikiWord* reference in the rendered HTML using a compiled regular expression. -- cgit v1.2.3 From 2d931400b22f4c5764df68c2799be512e60a2de1 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 18 Mar 2013 21:00:50 -0700 Subject: support acl as a callable --- docs/narr/security.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 5b79edd19..36c888559 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -270,6 +270,27 @@ resource instances with an ACL (as opposed to just decorating their class) in applications such as "CMS" systems where fine-grained access is required on an object-by-object basis. +Dynamic ACLs are also possible by turning the ACL into a callable on the +resource. This may allow the ACL to dynamically generate rules based on +properties of the instance. + +.. code-block:: python + :linenos: + + from pyramid.security import Allow + from pyramid.security import Everyone + + class Blog(object): + def __acl__(self): + return [ + (Allow, Everyone, 'view'), + (Allow, self.owner, 'edit'), + (Allow, 'group:editors', 'edit'), + ] + + def __init__(self, owner): + self.owner = owner + .. index:: single: ACE single: access control entry -- cgit v1.2.3 From 81e84fe86bee0c2753674fdaead001803936a2ba Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 18 Mar 2013 21:53:35 -0700 Subject: reorder some imports to be alphabetical --- docs/narr/security.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 36c888559..203aa2404 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -234,8 +234,8 @@ class: .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone class Blog(object): __acl__ = [ @@ -250,8 +250,8 @@ Or, if your resources are persistent, an ACL might be specified via the .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone class Blog(object): pass @@ -303,8 +303,8 @@ Here's an example ACL: .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone __acl__ = [ (Allow, Everyone, 'view'), @@ -342,9 +342,9 @@ order dictated by the ACL*. So if you have an ACL like this: .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow from pyramid.security import Deny + from pyramid.security import Everyone __acl__ = [ (Allow, Everyone, 'view'), @@ -380,8 +380,8 @@ ACE, as below. .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone __acl__ = [ (Allow, Everyone, 'view'), -- cgit v1.2.3 From 6842561d909ca041cb02d4152f4df3f5c6e57eab Mon Sep 17 00:00:00 2001 From: Steven Citron-Pousty Date: Tue, 19 Mar 2013 12:43:53 -0700 Subject: More explanation around pcreate Not sure how much to explain there but it needed some more explanation. Perhaps we could link to a doc about pcreate? --- docs/tutorials/wiki2/installation.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 255a60ec2..64e069e6f 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -66,6 +66,13 @@ On Windows: startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths. +Pcreate is a script that comes with Pyramid that helps by creating and organizing files +needed as part of a Pyramid project. By passing in `alchemy` was are asking the script to +create the files needed to use SQLAlchemy. By passing in our app name `tutorial` it goes through and +places that application name in all the different files required. For example, the ``initialize_tutorial_db`` +that is in the ``pyramidtut/bin`` directory that we use later in this tutorial was created by `pcreate` + + .. _installing_project_in_dev_mode: -- cgit v1.2.3 From ed214d879cab4f00f5151011279c69ea07da6540 Mon Sep 17 00:00:00 2001 From: Steven Citron-Pousty Date: Tue, 19 Mar 2013 13:00:29 -0700 Subject: fixed the syntax for exporting the VENV --- docs/narr/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 04a060ac3..9bc62dc62 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -269,7 +269,7 @@ you can then create a virtual environment. To do so, invoke the following: .. code-block:: text - $ export $VENV=~/env + $ export VENV=~/env $ virtualenv --no-site-packages $VENV New python executable in /home/foo/env/bin/python Installing setuptools.............done. -- cgit v1.2.3 From 1c9bdc5ba0f6317ed64bc120c3ebeeb5f089df62 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 19 Mar 2013 22:55:40 +0200 Subject: some improvements/fixes to a paragraph --- docs/tutorials/wiki2/installation.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 64e069e6f..253296b95 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -66,11 +66,11 @@ On Windows: startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths. -Pcreate is a script that comes with Pyramid that helps by creating and organizing files -needed as part of a Pyramid project. By passing in `alchemy` was are asking the script to -create the files needed to use SQLAlchemy. By passing in our app name `tutorial` it goes through and +`pcreate` is a script that comes with Pyramid that helps by creating and organizing files +needed as part of a Pyramid project. By passing in `alchemy`, we are asking the script to +create the files needed to use SQLAlchemy. By passing in our app name `tutorial`, the script places that application name in all the different files required. For example, the ``initialize_tutorial_db`` -that is in the ``pyramidtut/bin`` directory that we use later in this tutorial was created by `pcreate` +that is in the ``pyramidtut/bin`` directory was created by `pcreate`. -- cgit v1.2.3 From 07c189da9a9fa4a1a4231dbfff34ed77d09f73d1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 19 Mar 2013 23:10:56 -0700 Subject: Fix whitespace in CHANGES.txt to permit build. Add "Before You Begin" section. --- docs/tutorials/wiki2/installation.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 253296b95..8c4149bfc 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -2,13 +2,23 @@ Installation ============ -Preparation -=========== +Before You Begin +================ + +Installation Requirements +------------------------- Follow the steps in :ref:`installing_chapter`, but name the virtualenv -directory ``pyramidtut``. +directory ``pyramidtut``. Following these steps will ensure you have met the +following requirements: -Preparation, UNIX +* Python interpreter is installed on your operating system +* :term:`setuptools` or :term:`distribute` is installed +* :term:`virtualenv` is installed +* a virtual Python environment named ``pyramidtut`` has been created +* Pyramid is installed + +UNIX Requirements ----------------- #. Install SQLite3 and its development packages if you don't already @@ -25,8 +35,7 @@ Preparation, UNIX $ cd pyramidtut - -Preparation, Windows +Windows Requirements -------------------- #. Switch to the ``pyramidtut`` directory: -- cgit v1.2.3 From 7c47008ad76199dd5a638bc8c3a912664bd9c7d6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 20 Mar 2013 14:36:06 -0700 Subject: Add special section for Mac OS X users. --- docs/narr/install.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 9bc62dc62..0a03d9170 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -19,13 +19,32 @@ run :app:`Pyramid`. run under any version of Python before 2.6. :app:`Pyramid` is known to run on all popular UNIX-like systems such as -Linux, MacOS X, and FreeBSD as well as on Windows platforms. It is also -known to run on :term:`PyPy` (1.9+). +Linux, Mac OS X, and FreeBSD as well as on Windows platforms. It is +also known to run on :term:`PyPy` (1.9+). :app:`Pyramid` installation does not require the compilation of any C code, so you need only a Python interpreter that meets the requirements mentioned. +For Mac OS X Users +~~~~~~~~~~~~~~~~~~ + +From `Python.org `_: + + Python comes pre-installed on Mac OS X, but due to Apple's release + cycle, it's often one or even two years old. The overwhelming + recommendation of the "MacPython" community is to upgrade your + Python by downloading and installing a newer version from + `the Python standard release page `_. + +It is recommended to download one of the *installer* versions, unless you prefer to install your Python through a packgage manager (e.g., macports or homebrew) or to build your Python from source. + +Unless you have a need for a specific earlier version, it is recommended +to install the latest 2.x or 3.x version of Python. + +If you use an installer for your Python, then you can skip to the +section :ref:`installing_unix`. + If You Don't Yet Have A Python Interpreter (UNIX) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 7a8b0d3e9ab3ad73df9ec3110def55c38c527214 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 20 Mar 2013 14:39:11 -0700 Subject: Make installation explicit and discrete, combining suggestions from @thesteve0, @tshepang, @mcdonc. --- docs/tutorials/wiki2/installation.rst | 108 +++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 29 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 8c4149bfc..4b09f6eb7 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -5,25 +5,72 @@ Installation Before You Begin ================ -Installation Requirements -------------------------- - -Follow the steps in :ref:`installing_chapter`, but name the virtualenv -directory ``pyramidtut``. Following these steps will ensure you have met the -following requirements: +This tutorial assumes that you have already followed the steps in +:ref:`installing_chapter`, thereby satisfying the following +requirements. * Python interpreter is installed on your operating system * :term:`setuptools` or :term:`distribute` is installed * :term:`virtualenv` is installed -* a virtual Python environment named ``pyramidtut`` has been created -* Pyramid is installed -UNIX Requirements ------------------ +Create and Use a Virtual Python Environment +------------------------------------------- + +Next let's create a `virtualenv` workspace for our project. We will +use the `VENV` environment variable instead of absolute path of the +virtual environment. + +**On UNIX:** + +.. code-block:: text + + $ export VENV=~/pyramidtut + $ virtualenv --no-site-packages $VENV + New python executable in /home/foo/env/bin/python + Installing setuptools.............done. + +**On Windows:** + +Set the `VENV` environment variable. + +.. code-block:: text + + c:\> set VENV=c:\pyramidtut + +Versions of Python use different paths, so you will need to adjust the +path to the command for your Python version. -#. Install SQLite3 and its development packages if you don't already - have them installed. Usually this is via your system's package - manager. On a Debian system, this would be: +Python 2.7: + +.. code-block:: text + + c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV% + +Python 3.2: + +.. code-block:: text + + c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% + +Install Pyramid Into the Virtual Python Environment +--------------------------------------------------- + +**On UNIX:** + +.. code-block:: text + + $ $VENV/bin/easy_install pyramid + +**On Windows** + +.. code-block:: text + + c:\env> %VENV%\Scripts\easy_install pyramid + +SQLite3 +------- + +If you used a package manager to install your Python, or if you compiled your Python from source, then you must install SQLite3 and its development packages. If you downloaded your Python from python.org On a Debian system, this would be: .. code-block:: text @@ -49,10 +96,20 @@ Windows Requirements Making a Project ================ -Your next step is to create a project. For this tutorial, we will use the -:term:`scaffold` named ``alchemy``, which generates an application -that uses :term:`SQLAlchemy` and :term:`URL dispatch`. :app:`Pyramid` -supplies a variety of scaffolds to generate sample projects. +Your next step is to create a project. For this tutorial we will use +the :term:`scaffold` named ``alchemy`` which generates an application +that uses :term:`SQLAlchemy` and :term:`URL dispatch`. + +:app:`Pyramid` supplies a variety of scaffolds to generate sample +projects. We will use `pcreate`—a script that comes with Pyramid to +quickly and easily generate scaffolds usually with a single command—to +create the scaffold for our project. + +By passing in `alchemy` into the `pcreate` command, the script creates +the files needed to use SQLAlchemy. By passing in our application name +`tutorial`, the script inserts that application name into all the +required files. For example, `pcreate` creates the +``initialize_tutorial_db`` in the ``pyramidtut/bin`` directory. The below instructions assume your current working directory is the "virtualenv" named "pyramidtut". @@ -75,18 +132,10 @@ On Windows: startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths. -`pcreate` is a script that comes with Pyramid that helps by creating and organizing files -needed as part of a Pyramid project. By passing in `alchemy`, we are asking the script to -create the files needed to use SQLAlchemy. By passing in our app name `tutorial`, the script -places that application name in all the different files required. For example, the ``initialize_tutorial_db`` -that is in the ``pyramidtut/bin`` directory was created by `pcreate`. - - - .. _installing_project_in_dev_mode: -Installing the Project in "Development Mode" -============================================ +Installing the Project in Development Mode +========================================== In order to do development on the project easily, you must "register" the project as a development egg in your workspace using the @@ -108,8 +157,9 @@ On Windows: c:\pyramidtut> cd tutorial c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop -Success executing this command will end with a line to the console something -like:: +The console will show `setup.py` checking for packages and installing +missing packages. Success executing this command will show a line like +the following:: Finished processing dependencies for tutorial==0.0 -- cgit v1.2.3 From 9435d665b797e7a61410cf608d1f1bff4695c2f8 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 21 Mar 2013 01:54:00 +0200 Subject: revert to a better paragraph --- docs/tutorials/wiki2/installation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 4b09f6eb7..bb22371ab 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -70,7 +70,9 @@ Install Pyramid Into the Virtual Python Environment SQLite3 ------- -If you used a package manager to install your Python, or if you compiled your Python from source, then you must install SQLite3 and its development packages. If you downloaded your Python from python.org On a Debian system, this would be: +Install SQLite3 and its development packages if you don't already +have them installed. Usually this is via your system's package +manager. On a Debian system, this would be: .. code-block:: text -- cgit v1.2.3 From a4010d1b2d3e7c266c2369bb166cf2d7cfafc783 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 21 Mar 2013 02:03:20 +0200 Subject: slightly re-organise --- docs/tutorials/wiki2/installation.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 4b09f6eb7..f55c047ba 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -76,16 +76,17 @@ If you used a package manager to install your Python, or if you compiled your Py $ sudo apt-get install libsqlite3-dev -#. Switch to the ``pyramidtut`` directory: +Entering the virtualenv +----------------------- + +Do not forget to switch to the ``pyramidtut`` directory. +In order to do so, run this command if you are on Unix: .. code-block:: text $ cd pyramidtut -Windows Requirements --------------------- - -#. Switch to the ``pyramidtut`` directory: +And run this if you are on Windows: .. code-block:: text -- cgit v1.2.3 From f1c29f104a14dea0be612ca0aa8ecd49e165fafa Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 21 Mar 2013 18:24:31 +0200 Subject: add hyperlinks for SQLAlchemy --- docs/conf.py | 1 + docs/tutorials/wiki2/basiclayout.rst | 6 +++--- docs/tutorials/wiki2/definingmodels.rst | 9 +++++---- 3 files changed, 9 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 8d22d4d42..b763267dd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,6 +55,7 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { + 'sqla': ('http://docs.sqlalchemy.org/en/rel_0_8/', None), 'who': ('http://docs.repoze.org/who/2.0', None), 'python': ('http://docs.python.org', None), 'python3': ('http://docs.python.org/3', None), diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 86fe97956..eb2445864 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -43,9 +43,9 @@ above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) The main function first creates a :term:`SQLAlchemy` database engine using -``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the -``development.ini`` file's ``[app:main]`` section. This will be a URI -(something like ``sqlite://``): +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed +settings in the ``development.ini`` file's ``[app:main]`` section. +This will be a URI (something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 13 diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index bd1cb00d7..d55da02cd 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -34,7 +34,7 @@ sample and we're not going to use it. Then, we added a ``Page`` class. Because this is a SQLAlchemy application, this class inherits from an instance of -:class:`sqlalchemy.ext.declarative.declarative_base`. +:func:`sqlalchemy.ext.declarative.declarative_base`. .. literalinclude:: src/models/tutorial/models.py :pyobject: Page @@ -45,9 +45,10 @@ As you can see, our ``Page`` class has a class level attribute ``__tablename__`` which equals the string ``'pages'``. This means that SQLAlchemy will store our wiki data in a SQL table named ``pages``. Our ``Page`` class will also have class-level attributes named ``id``, ``name`` and -``data`` (all instances of :class:`sqlalchemy.Column`). These will map to -columns in the ``pages`` table. The ``id`` attribute will be the primary key -in the table. The ``name`` attribute will be a text attribute, each value of +``data`` (all instances of :class:`sqlalchemy.schema.Column`). +These will map to columns in the ``pages`` table. +The ``id`` attribute will be the primary key in the table. +The ``name`` attribute will be a text attribute, each value of which needs to be unique within the column. The ``data`` attribute is a text attribute that will hold the body of each page. -- cgit v1.2.3 From 39b8a29a48d716b3381596fe71cddf6c59393518 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 21 Mar 2013 18:37:28 +0200 Subject: use version-agnostic link, to avoid maintenance --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index b763267dd..d1a882389 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,7 +55,7 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { - 'sqla': ('http://docs.sqlalchemy.org/en/rel_0_8/', None), + 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), 'who': ('http://docs.repoze.org/who/2.0', None), 'python': ('http://docs.python.org', None), 'python3': ('http://docs.python.org/3', None), -- cgit v1.2.3 From 2a65f2086ce5b0c2f029fbc0ea165a65cd601ec3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 21 Mar 2013 18:52:07 +0200 Subject: four spaces is standard --- docs/conf.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index d1a882389..89eb998e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,14 +55,14 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { - 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), - 'who': ('http://docs.repoze.org/who/2.0', None), - 'python': ('http://docs.python.org', None), - 'python3': ('http://docs.python.org/3', None), - 'tstring': + 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), + 'who': ('http://docs.repoze.org/who/2.0', None), + 'python': ('http://docs.python.org', None), + 'python3': ('http://docs.python.org/3', None), + 'tstring': ('http://docs.pylonsproject.org/projects/translationstring/en/latest', None), - 'venusian': + 'venusian': ('http://docs.pylonsproject.org/projects/venusian/en/latest', None), } -- cgit v1.2.3 From 09bca9c5ed0e66699762d66b09be899e86967899 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 21 Mar 2013 12:40:02 -0500 Subject: update repoze.who to latest symlink --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 89eb998e7..eff6db488 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,7 +56,7 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), - 'who': ('http://docs.repoze.org/who/2.0', None), + 'who': ('http://docs.repoze.org/who/latest', None), 'python': ('http://docs.python.org', None), 'python3': ('http://docs.python.org/3', None), 'tstring': -- cgit v1.2.3 From 203fe8b2a92c18151894f0656b7846cef8ec4e51 Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 12:00:43 -0700 Subject: Update basiclayout.rst, more deductive concept ordering, singular form of terms --- docs/tutorials/wiki2/basiclayout.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index eb2445864..109d368b8 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -132,11 +132,11 @@ Finally, ``main`` is finished configuring things, so it uses the View Declarations via ``views.py`` ---------------------------------- -Mapping a :term:`route` to code that will be executed when a match for -the route's pattern occurs is done by registering a :term:`view -configuration`. Our application uses the -:meth:`pyramid.view.view_config` decorator to map view callables to -each route, thereby mapping URL patterns to code. +Arguably, the main function of a web framework is mapping each URL +patterns, see :term:`route`, to code, see :term:`view callable`, that is +executed when the requested URL matches the corresponding :term:`route`. Our +application uses the :meth:`pyramid.view.view_config` decorator to perform +this mapping. Open ``tutorial/tutorial/views.py``. It should already contain the following: -- cgit v1.2.3 From 124daa3f3de2350ee4079d684736acd10b415046 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 21 Mar 2013 13:27:14 -0700 Subject: Clean up: * SQLite3 language * cd into venv * minor heading names --- docs/tutorials/wiki2/installation.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 4b09f6eb7..a8b8ee877 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -67,25 +67,34 @@ Install Pyramid Into the Virtual Python Environment c:\env> %VENV%\Scripts\easy_install pyramid -SQLite3 -------- +Install SQLite3 and Its Development Packages +-------------------------------------------- -If you used a package manager to install your Python, or if you compiled your Python from source, then you must install SQLite3 and its development packages. If you downloaded your Python from python.org On a Debian system, this would be: +If you used a package manager to install your Python or if you compiled +your Python from source, then you must install SQLite3 and its +development packages. If you downloaded your Python as an installer +from python.org, then you already have it installed and can proceed to +the next section :ref:`sql_making_a_project`.. + +If you need to install the SQLite3 packages, then, for example, using +the Debian system and apt-get, the command would be the following: .. code-block:: text $ sudo apt-get install libsqlite3-dev -#. Switch to the ``pyramidtut`` directory: +Change Directory to Your Virtual Python Environment +--------------------------------------------------- + +Change directory to the ``pyramidtut`` directory. + +**On UNIX:** .. code-block:: text $ cd pyramidtut -Windows Requirements --------------------- - -#. Switch to the ``pyramidtut`` directory: +**On Windows** .. code-block:: text @@ -358,4 +367,3 @@ the following assumptions: mechanism to map URLs to code (:term:`traversal`). However, for the purposes of this tutorial, we'll only be using url dispatch and SQLAlchemy. - -- cgit v1.2.3 From b1611cf0d24e2947ebfb58071ff7c695a1d824cc Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 13:05:41 -0700 Subject: Update definingviews.rst explain matchdict more explicitly, concisely --- docs/tutorials/wiki2/basiclayout.rst | 9 ++++----- docs/tutorials/wiki2/definingviews.rst | 15 +++++++-------- 2 files changed, 11 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 109d368b8..6d6287126 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -228,11 +228,10 @@ To give a simple example of a model class, we define one named ``MyModel``: Our example model has an ``__init__`` method that takes two arguments (``name``, and ``value``). It stores these values as ``self.name`` and -``self.value`` -within the ``__init__`` function itself. The ``MyModel`` class also has a -``__tablename__`` attribute. This informs SQLAlchemy which table to use to -store the data representing instances of this class. +``self.value`` within the ``__init__`` function itself. The ``MyModel`` class +also has a ``__tablename__`` attribute. This informs SQLAlchemy which table +to use to store the data representing instances of this class. -That's about all there is to it to models, views, and initialization code in +That's about all there is to it with models, views, and initialization code in our stock application. diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index f2ac2f85f..72cba8d1e 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -6,14 +6,13 @@ A :term:`view callable` in a :app:`Pyramid` application is typically a simple Python function that accepts a single parameter named :term:`request`. A view callable is assumed to return a :term:`response` object. -The request object passed to every view that is called as the result of a -route match has an attribute named ``matchdict`` that contains the elements -placed into the URL by the ``pattern`` of a ``route`` statement. For -instance, if a call to :meth:`pyramid.config.Configurator.add_route` in -``__init__.py`` had the pattern ``{one}/{two}``, and the URL at -``http://example.com/foo/bar`` was invoked, matching this pattern, the -``matchdict`` dictionary attached to the request passed to the view would -have a ``'one'`` key with the value ``'foo'`` and a ``'two'`` key with the +The request object has an attribute named ``matchdict``. A ``matchdict`` maps +the placeholders in the matching URL ``pattern`` to the substrings of the +:term:`request` ed URL. For instance, if a call to +:meth:`pyramid.config.Configurator.add_route` in ``__init__.py`` had the pattern +``{one}/{two}``, and the URL at ``http://example.com/foo/bar`` was invoked, matching +this pattern, the ``matchdict`` dictionary attached to the request passed to the view +would have a ``'one'`` key with the value ``'foo'`` and a ``'two'`` key with the value ``'bar'``. -- cgit v1.2.3 From b4eeddf672987c8f03058f5bf0d4f7080007b0e2 Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 14:12:23 -0700 Subject: Update definingviews.rst to be more explicit, concise (?) A make the first sentence a litte more explicit, default to present tense, remove unnecessary details and use python instead of english when it's cleared to do so. --- docs/tutorials/wiki2/definingviews.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 72cba8d1e..9df72c926 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -6,14 +6,12 @@ A :term:`view callable` in a :app:`Pyramid` application is typically a simple Python function that accepts a single parameter named :term:`request`. A view callable is assumed to return a :term:`response` object. -The request object has an attribute named ``matchdict``. A ``matchdict`` maps -the placeholders in the matching URL ``pattern`` to the substrings of the -:term:`request` ed URL. For instance, if a call to -:meth:`pyramid.config.Configurator.add_route` in ``__init__.py`` had the pattern -``{one}/{two}``, and the URL at ``http://example.com/foo/bar`` was invoked, matching -this pattern, the ``matchdict`` dictionary attached to the request passed to the view -would have a ``'one'`` key with the value ``'foo'`` and a ``'two'`` key with the -value ``'bar'``. +The request object has a dictionary as an attribute named ``matchdict``. +A ``matchdict`` maps the placeholders in the matching URL ``pattern`` to the substrings +of the :term:`request` ed URL. For instance, if a call to +:meth:`pyramid.config.Configurator.add_route` has the pattern +``{one}/{two}``, and the URL at ``http://example.com/foo/bar`` is invoked, matching +this pattern, the ``matchdict`` attached to the request would look like: ``{'one':'foo', 'two':'bar'}`` Declaring Dependencies in Our ``setup.py`` File -- cgit v1.2.3 From e163c0931e17c3ad79dd0fa08cea924db1813558 Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 14:16:57 -0700 Subject: Update definingviews.rst to use active voice, reduce redundancy. --- docs/tutorials/wiki2/definingviews.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 9df72c926..f733abe10 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -10,8 +10,8 @@ The request object has a dictionary as an attribute named ``matchdict``. A ``matchdict`` maps the placeholders in the matching URL ``pattern`` to the substrings of the :term:`request` ed URL. For instance, if a call to :meth:`pyramid.config.Configurator.add_route` has the pattern -``{one}/{two}``, and the URL at ``http://example.com/foo/bar`` is invoked, matching -this pattern, the ``matchdict`` attached to the request would look like: ``{'one':'foo', 'two':'bar'}`` +``{one}/{two}``, and a user visits ``http://example.com/foo/bar``, our pattern would be +matched and the ``matchdict`` would look like: ``{'one':'foo', 'two':'bar'}`` Declaring Dependencies in Our ``setup.py`` File -- cgit v1.2.3 From bb8e20e0d35dc806e19edc6d07c837ec272128ec Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 17:24:51 -0700 Subject: Update definingviews.rst to clarify that a template is a renderer --- docs/tutorials/wiki2/definingviews.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index f733abe10..9894bcb08 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -149,10 +149,9 @@ We then generate an edit URL (because it's easier to do here than in the template), and we return a dictionary with a number of arguments. The fact that ``view_page()`` returns a dictionary (as opposed to a :term:`response` object) is a cue to :app:`Pyramid` that it should try to use a :term:`renderer` -associated with the view configuration to render a template. In our case, -the template which will be rendered will be the ``templates/view.pt`` -template, as indicated in the ``@view_config`` decorator that is applied to -``view_page()``. +associated with the view configuration to render a response. In our case, +the renderer used will be the ``templates/view.pt`` template, as indicated in +the ``@view_config`` decorator that is applied to ``view_page()``. The ``add_page`` view function ------------------------------ -- cgit v1.2.3 From 1ec39d51636ec72ef55b6bfb6c3115cc0be7c160 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 21 Mar 2013 13:40:10 -0700 Subject: Meh. git hate me. --- docs/tutorials/wiki2/installation.rst | 17 ----------------- 1 file changed, 17 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index dd7c76d5f..4361f18e8 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -70,7 +70,6 @@ Install Pyramid Into the Virtual Python Environment Install SQLite3 and Its Development Packages -------------------------------------------- -<<<<<<< HEAD If you used a package manager to install your Python or if you compiled your Python from source, then you must install SQLite3 and its development packages. If you downloaded your Python as an installer @@ -79,40 +78,24 @@ the next section :ref:`sql_making_a_project`.. If you need to install the SQLite3 packages, then, for example, using the Debian system and apt-get, the command would be the following: -======= -Install SQLite3 and its development packages if you don't already -have them installed. Usually this is via your system's package -manager. On a Debian system, this would be: ->>>>>>> upstream/master .. code-block:: text $ sudo apt-get install libsqlite3-dev -<<<<<<< HEAD Change Directory to Your Virtual Python Environment --------------------------------------------------- Change directory to the ``pyramidtut`` directory. **On UNIX:** -======= -Entering the virtualenv ------------------------ - -Do not forget to switch to the ``pyramidtut`` directory. -In order to do so, run this command if you are on Unix: ->>>>>>> upstream/master .. code-block:: text $ cd pyramidtut -<<<<<<< HEAD **On Windows** ======= -And run this if you are on Windows: ->>>>>>> upstream/master .. code-block:: text -- cgit v1.2.3 From 21d0288a9211b175f61769d7e7cf471f12ee09cb Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 21 Mar 2013 14:03:03 -0700 Subject: Generalize Python versions in Windows section. --- docs/narr/install.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 0a03d9170..7f4742ee2 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -341,8 +341,8 @@ for both versions are included below. Windows Using Python 2 ~~~~~~~~~~~~~~~~~~~~~~ -#. Install, or find `Python 2.7 - `_ for your system. +#. Install, or find the most recent `Python 2.7.x version + `_ for your system. #. Install the `Python for Windows extensions `_. Make sure to @@ -390,36 +390,47 @@ Windows Using Python 2 Windows Using Python 3 ~~~~~~~~~~~~~~~~~~~~~~ -#. Install, or find `Python 3.2 - `_ for your system. +#. Install, or find the latest version of `Python 3.x + `_ for your system and which is + supported by Pyramid. #. Install the `Python for Windows extensions `_. Make sure to - pick the right download for Python 3.2 and install it using the + pick the right download for Python 3.x and install it using the same Python installation from the previous step. #. Install latest :term:`distribute` distribution into the Python you obtained/installed/found in the step above: download `distribute_setup.py `_ and run it using the - ``python`` interpreter of your Python 3.2 installation using a command + ``python`` interpreter of your Python 3.x installation using a command prompt: .. code-block:: text + # modify the command according to the python version, e.g.: + # for Python 3.2.x: c:\> c:\Python32\python distribute_setup.py + # for Python 3.3.x: + c:\> c:\Python33\python distribute_setup.py #. Install :term:`virtualenv`: .. code-block:: text + # for Python 3.2.x: c:\> c:\Python32\Scripts\easy_install virtualenv + # for Python 3.3.x: + c:\> c:\Python33\Scripts\easy_install virtualenv #. Make a :term:`virtualenv` workspace: .. code-block:: text c:\> set VENV=c:\env + # for Python 3.2.x: c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% + # for Python 3.3.x: + c:\> c:\Python33\Scripts\virtualenv --no-site-packages %VENV% You can either follow the use of the environment variable, ``%VENV%``, or replace it with the root directory of the :term:`virtualenv`. -- cgit v1.2.3 From 2f7320c4fcf38ee95e2aa97228e30c9a873ef1f9 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Mar 2013 01:36:29 +0200 Subject: some consistency fixes --- docs/tutorials/wiki2/installation.rst | 49 +++++++++++++++++------------------ 1 file changed, 24 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 4361f18e8..9590e4abe 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -29,7 +29,7 @@ virtual environment. New python executable in /home/foo/env/bin/python Installing setuptools.............done. -**On Windows:** +**On Windows**: Set the `VENV` environment variable. @@ -61,7 +61,7 @@ Install Pyramid Into the Virtual Python Environment $ $VENV/bin/easy_install pyramid -**On Windows** +**On Windows**: .. code-block:: text @@ -79,27 +79,26 @@ the next section :ref:`sql_making_a_project`.. If you need to install the SQLite3 packages, then, for example, using the Debian system and apt-get, the command would be the following: - .. code-block:: text +.. code-block:: text - $ sudo apt-get install libsqlite3-dev + $ sudo apt-get install libsqlite3-dev Change Directory to Your Virtual Python Environment --------------------------------------------------- Change directory to the ``pyramidtut`` directory. -**On UNIX:** +**On UNIX**: - .. code-block:: text +.. code-block:: text - $ cd pyramidtut + $ cd pyramidtut -**On Windows** -======= +**On Windows**: - .. code-block:: text +.. code-block:: text - c:\> cd pyramidtut + c:\> cd pyramidtut .. _sql_making_a_project: @@ -124,13 +123,13 @@ required files. For example, `pcreate` creates the The below instructions assume your current working directory is the "virtualenv" named "pyramidtut". -On UNIX: +**On UNIX**: .. code-block:: text $ $VENV/bin/pcreate -s alchemy tutorial -On Windows: +**On Windows**: .. code-block:: text @@ -153,14 +152,14 @@ the project as a development egg in your workspace using the directory you created in :ref:`sql_making_a_project`, and run the ``setup.py develop`` command using the virtualenv Python interpreter. -On UNIX: +**On UNIX**: .. code-block:: text $ cd tutorial $ $VENV/bin/python setup.py develop -On Windows: +**On Windows**: .. code-block:: text @@ -181,13 +180,13 @@ Running the Tests After you've installed the project in development mode, you may run the tests for the project. -On UNIX: +**On UNIX**: .. code-block:: text $ $VENV/bin/python setup.py test -q -On Windows: +**On Windows**: .. code-block:: text @@ -213,13 +212,13 @@ tests. To get this functionality working, we'll need to install the ``nose`` and ``coverage`` packages into our ``virtualenv``: -On UNIX: +**On UNIX**: .. code-block:: text $ $VENV/bin/easy_install nose coverage -On Windows: +**On Windows**: .. code-block:: text @@ -228,13 +227,13 @@ On Windows: Once ``nose`` and ``coverage`` are installed, we can actually run the coverage tests. -On UNIX: +**On UNIX**: .. code-block:: text $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage -On Windows: +**On Windows**: .. code-block:: text @@ -272,13 +271,13 @@ script` to initialize our database. Type the following command, make sure you are still in the ``tutorial`` directory (the directory with a ``development.ini`` in it): -On UNIX: +**On UNIX**: .. code-block:: text $ $VENV/bin/initialize_tutorial_db development.ini -On Windows: +**On Windows**: .. code-block:: text @@ -320,13 +319,13 @@ Starting the Application Start the application. -On UNIX: +**On UNIX**: .. code-block:: text $ $VENV/bin/pserve development.ini --reload -On Windows: +**On Windows**: .. code-block:: text -- cgit v1.2.3 From 1ad8de2b9032b5a452b75274b8f908645c732e57 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Mar 2013 17:24:32 +0200 Subject: remove unused ignore-next-block directive --- docs/designdefense.rst | 3 --- docs/narr/assets.rst | 6 ------ docs/narr/configuration.rst | 1 - docs/narr/firstapp.rst | 3 --- docs/narr/security.rst | 2 -- docs/narr/templates.rst | 1 - docs/narr/urldispatch.rst | 1 - docs/narr/viewconfig.rst | 2 -- docs/narr/webob.rst | 2 -- docs/narr/zca.rst | 1 - 10 files changed, 22 deletions(-) (limited to 'docs') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 749c9b099..7bc37ac06 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -120,7 +120,6 @@ that uses the ZCA global API is somewhat high. Consider a ZCA neophyte reading the code that performs a typical "unnamed utility" lookup using the :func:`zope.component.getUtility` global API: -.. ignore-next-block .. code-block:: python :linenos: @@ -190,7 +189,6 @@ special-purpose API functions that *do* use ZCA APIs. Take for example the present in the current request or ``None`` if no userid is present in the current request. The application developer calls it like so: -.. ignore-next-block .. code-block:: python :linenos: @@ -500,7 +498,6 @@ which match information in an associated "urlconf" such as Zope, likewise allows you to add arbitrary keyword and positional arguments to any method of a resource object found via traversal: -.. ignore-next-block .. code-block:: python :linenos: diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index deaf0ce08..99bcb187f 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -50,7 +50,6 @@ application might address the asset using the :term:`asset specification` ``myapp:templates/some_template.pt`` using that API within a ``views.py`` file inside a ``myapp`` package: -.. ignore-next-block .. code-block:: python :linenos: @@ -331,7 +330,6 @@ root that exists at the end of your routing table, create an instance of the :class:`~pyramid.static.static_view` class inside a ``static.py`` file in your application root as below. -.. ignore-next-block .. code-block:: python :linenos: @@ -458,7 +456,6 @@ The ``override_asset`` API An individual call to :meth:`~pyramid.config.Configurator.override_asset` can override a single asset. For example: -.. ignore-next-block .. code-block:: python :linenos: @@ -473,7 +470,6 @@ colon separator in a specification separates the *package name* from the are not specified, the override attempts to resolve every lookup into a package from the directory of another package. For example: -.. ignore-next-block .. code-block:: python :linenos: @@ -482,7 +478,6 @@ package from the directory of another package. For example: Individual subdirectories within a package can also be overridden: -.. ignore-next-block .. code-block:: python :linenos: @@ -511,7 +506,6 @@ construction file resides (or the ``package`` argument to the :class:`~pyramid.config.Configurator` class construction). For example: -.. ignore-next-block .. code-block:: python :linenos: diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 6f82baf32..f7a69d613 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -140,7 +140,6 @@ In the example above, the scanner translates the arguments to :class:`~pyramid.view.view_config` into a call to the :meth:`pyramid.config.Configurator.add_view` method, effectively: -.. ignore-next-block .. code-block:: python config.add_view(hello) diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 6d3786d8e..e73ef66ac 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -166,7 +166,6 @@ the application. Adding Configuration ~~~~~~~~~~~~~~~~~~~~ -.. ignore-next-block .. literalinclude:: helloworld.py :linenos: :lines: 11-12 @@ -186,7 +185,6 @@ The second line registers the ``hello_world`` function as a WSGI Application Creation ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. ignore-next-block .. literalinclude:: helloworld.py :linenos: :lines: 13 @@ -215,7 +213,6 @@ to its ``add_view`` and ``add_route`` methods. WSGI Application Serving ~~~~~~~~~~~~~~~~~~~~~~~~ -.. ignore-next-block .. literalinclude:: helloworld.py :linenos: :lines: 14-15 diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 203aa2404..e91e8c542 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -85,7 +85,6 @@ during application setup to specify the authentication policy. For example: -.. ignore-next-block .. code-block:: python :linenos: @@ -151,7 +150,6 @@ API: The equivalent view registration including the ``add`` permission name may be performed via the ``@view_config`` decorator: -.. ignore-next-block .. code-block:: python :linenos: diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 1f1c07027..d4cf20b93 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -150,7 +150,6 @@ string, then return that string as the body of a :app:`Pyramid` For example, here's an example of using "raw" `Mako `_ from within a :app:`Pyramid` :term:`view`: -.. ignore-next-block .. code-block:: python :linenos: diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 0656a1833..bcd5fff94 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -55,7 +55,6 @@ The :meth:`pyramid.config.Configurator.add_route` method adds a single :term:`route configuration` to the :term:`application registry`. Here's an example: -.. ignore-next-block .. code-block:: python # "config" below is presumed to be an instance of the diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index e0338c442..14a2fc807 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -488,7 +488,6 @@ acts as a :app:`Pyramid` view callable. Here's an example of the :class:`~pyramid.view.view_config` decorator that lives within a :app:`Pyramid` application module ``views.py``: -.. ignore-next-block .. code-block:: python :linenos: @@ -503,7 +502,6 @@ lives within a :app:`Pyramid` application module ``views.py``: Using this decorator as above replaces the need to add this imperative configuration stanza: -.. ignore-next-block .. code-block:: python :linenos: diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 44940f9e6..63a08adaa 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -326,7 +326,6 @@ package that uses SQLAlchemy, and you'd like the current SQLAlchemy database session to be removed after each request. Put the following in the ``mypackage.__init__`` module: -.. ignore-next-block .. code-block:: python :linenos: @@ -491,7 +490,6 @@ reason for the error. For instance, :class:`pyramid.Response`, so you can manipulate the instances in the same way. A typical example is: -.. ignore-next-block .. code-block:: python :linenos: diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst index f7707ea29..5499cf4a5 100644 --- a/docs/narr/zca.rst +++ b/docs/narr/zca.rst @@ -21,7 +21,6 @@ application can be opaque. For example, here is a typical "unnamed utility" lookup using the :func:`zope.component.getUtility` global API as it might appear in a traditional Zope application: -.. ignore-next-block .. code-block:: python :linenos: -- cgit v1.2.3 From 7c62a15eff2fc4c7cdd76e4b71b3123ff9172825 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Mar 2013 18:53:23 +0200 Subject: rm unused glossary entry --- docs/glossary.rst | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 40c15efdc..1b7a5f307 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -334,12 +334,6 @@ Glossary `Zope Object Database `_, a persistent Python object store. - ZEO - `Zope Enterprise Objects - `_ - allows multiple simultaneous processes to access a single - :term:`ZODB` database. - WebOb `WebOb `_ is a WSGI request/response library created by Ian Bicking. -- cgit v1.2.3