From 44436e1240f497e598de7b316ffaf7b6b8665452 Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Tue, 3 Sep 2013 18:30:56 -0600 Subject: Removed unnecessary side bar with duplicate content The side-bar contained a duplication of code that was already in the main article. Adding a note instead and removing the side-bar provides the same information without nearly as much duplication. --- docs/narr/traversal.rst | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index a60c5ba56..fb4adff61 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -128,6 +128,12 @@ Here's an example of a simple root factory class: def __init__(self, request): pass +..note:: + For the purpose of understanding traversal, and the contents within + this document, the above Root is an analogue to the default root + factory present in Pyramid. The default root factory is very simple and + not very useful unless using :term:`URL dispatch`. + Here's an example of using this root factory within startup configuration, by passing it to an instance of a :term:`Configurator` named ``config``: @@ -154,28 +160,6 @@ Usually a root factory for a traversal-based application will be more complicated than the above ``Root`` class; in particular it may be associated with a database connection or another persistence mechanism. -.. sidebar:: Emulating the Default Root Factory - - For purposes of understanding the default root factory better, we'll note - that you can emulate the default root factory by using this code as an - explicit root factory in your application setup: - - .. code-block:: python - :linenos: - - class Root(object): - def __init__(self, request): - pass - - config = Configurator(root_factory=Root) - - The default root factory is just a really stupid object that has no - behavior or state. Using :term:`traversal` against an application that - uses the resource tree supplied by the default root resource is not very - interesting, because the default root resource has no children. Its - availability is more useful when you're developing an application using - :term:`URL dispatch`. - .. note:: If the items contained within the resource tree are "persistent" (they -- cgit v1.2.3 From ae5f2b9da9583114f3f5a6f08497e5a248e3e960 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 27 Sep 2013 20:47:28 -0500 Subject: Docs: Make clear that installation is into the virtual enviornment. --- docs/narr/project.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index f3050f805..602f15fef 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -193,10 +193,10 @@ Elided output from a run of this command on UNIX is shown below: ... Finished processing dependencies for MyProject==0.0 -This will install a :term:`distribution` representing your project into the -interpreter's library set so it can be found by ``import`` statements and by -other console scripts such as ``pserve``, ``pshell``, ``proutes`` and -``pviews``. +This will install a :term:`distribution` representing your project +into the virtual environment interpreter's library set so it can be +found by ``import`` statements and by other console scripts such as +``pserve``, ``pshell``, ``proutes`` and ``pviews``. .. index:: single: running tests -- cgit v1.2.3 From 2323103debf8487d0a0a1ec27580e502d46989e3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 28 Sep 2013 02:19:27 -0700 Subject: Add versioning to branch master --- docs/narr/install.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index f3f736df6..e419a8b20 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -289,9 +289,9 @@ Installing :app:`Pyramid` Into the Virtual Python Environment After you've got your virtualenv installed, you may install :app:`Pyramid` itself using the following commands: -.. code-block:: text - - $ $VENV/bin/easy_install pyramid +.. parsed-literal:: + + $ $VENV/bin/easy_install "pyramid==\ |release|\ " The ``easy_install`` command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies. @@ -368,9 +368,9 @@ You can use Pyramid on Windows under Python 2 or 3. #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies installed: - .. code-block:: text - - c:\env> %VENV%\Scripts\easy_install pyramid + .. parsed-literal:: + + c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " What Gets Installed ------------------- -- cgit v1.2.3 From bc3de3f5499e39e67e29b6678503f3a14be0b08c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 1 Oct 2013 00:14:12 -0500 Subject: Docs: project.rst: Match parenthesis & fix punctuation. --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 602f15fef..fc3cac009 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -974,9 +974,9 @@ named ``views`` instead of within a single ``views.py`` file, you might: - *Move* the existing ``views.py`` file to a file inside the new ``views`` directory named, say, ``blog.py``. -- Create a file within the new ``views`` directory named ``__init__.py`` (it - can be empty, this just tells Python that the ``views`` directory is a - *package*. +- Create a file within the new ``views`` directory named ``__init__.py``. (It + can be empty. This just tells Python that the ``views`` directory is a + *package*.) You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable -- cgit v1.2.3 From 128d9d6cd92ddd50dfcdf14b12cc94a0902c0df1 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 1 Oct 2013 00:22:20 -0500 Subject: Docs: project.rst: Note that asset specs must be fully qualifed when moving views into a sub-package. --- docs/narr/project.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fc3cac009..1b98271fb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -971,13 +971,16 @@ named ``views`` instead of within a single ``views.py`` file, you might: - Create a ``views`` directory inside your ``myproject`` package directory (the same directory which holds ``views.py``). -- *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. - - Create a file within the new ``views`` directory named ``__init__.py``. (It can be empty. This just tells Python that the ``views`` directory is a *package*.) +- *Move* the existing ``views.py`` file to a file inside the new ``views`` + directory named, say, ``blog.py``. The template :term:`asset + specification`s in ``blog.py`` must now be fully qualified with the + project's package name (``myproject:templates/blog.pt``) since the + ``templates`` directory remains in the ``myproject`` package. + You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable functions to the ``views`` directory. As long as you use the -- cgit v1.2.3 From ac7d1752e071fb7dadbfbf7f4bd1efadd3052b4f Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 1 Oct 2013 00:44:16 -0500 Subject: Docs: project.rst: Make the sentence more better. --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 1b98271fb..e5da3b5c5 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -976,10 +976,10 @@ named ``views`` instead of within a single ``views.py`` file, you might: *package*.) - *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. The template :term:`asset + directory named, say, ``blog.py``. Because the ``templates`` directory + remains in the ``myproject`` package the template :term:`asset specification`s in ``blog.py`` must now be fully qualified with the - project's package name (``myproject:templates/blog.pt``) since the - ``templates`` directory remains in the ``myproject`` package. + project's package name (``myproject:templates/blog.pt``). You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable -- cgit v1.2.3 From 1a76ed41b133ea73c7d40997c6f564fd72d7273e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 1 Oct 2013 00:48:53 -0700 Subject: Add comma --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index e5da3b5c5..4c19982d6 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -144,7 +144,7 @@ contains no space characters, so it's wise to *avoid* a path that contains i.e. ``My Documents``. As a result, the author, when he uses Windows, just puts his projects in ``C:\projects``. -.. warning:: +.. warning:: You’ll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you @@ -977,7 +977,7 @@ named ``views`` instead of within a single ``views.py`` file, you might: - *Move* the existing ``views.py`` file to a file inside the new ``views`` directory named, say, ``blog.py``. Because the ``templates`` directory - remains in the ``myproject`` package the template :term:`asset + remains in the ``myproject`` package, the template :term:`asset specification`s in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). @@ -1028,7 +1028,7 @@ server. Waitress is a server that is suited for development and light production usage. It's not the fastest nor the most featureful WSGI server. Instead, its main feature is that it works on all platforms that Pyramid needs to run on, making it a good choice as a default server from the -perspective of Pyramid's developers. +perspective of Pyramid's developers. Any WSGI server is capable of running a :app:`Pyramid` application. But we suggest you stick with the default server for development, and that you wait -- cgit v1.2.3 From f24ac4c471a458aec0cde232925c8fab652bafcc Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 11:31:47 -0500 Subject: Docs: project.rst: Eliminate reduncency and better explain renderer. --- docs/narr/project.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 602f15fef..09e07ee6d 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -871,18 +871,17 @@ specification` that specifies the ``mytemplate.pt`` file within the ``templates`` directory of the ``myproject`` package. The asset specification could have also been specified as ``myproject:templates/mytemplate.pt``; the leading package name and colon is -optional. The template file it actually points to is a :term:`Chameleon` ZPT -template file. +optional. The template file pointed to is a :term:`Chameleon` ZPT +template file (``templates/my_template.pt``). This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -This view returns a dictionary. When this view is invoked, a -:term:`renderer` converts the dictionary returned by the view into HTML, and -returns the result as the :term:`response`. This view is configured to -invoke a renderer which uses a :term:`Chameleon` ZPT template -(``templates/my_template.pt``). +This view is configured to invoke a :term;`renderer` on a template. The +dictionary the view returns (on line 6) provides the value the renderer +substitutes into the template when generating HTML. The renderer then +returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -- cgit v1.2.3 From 77edee7e91356f4f0f1d12c2dd159965b0576109 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 11:33:50 -0500 Subject: Docs: project.rst: Emphasize key takeaway; use dicts to supply values to templates. --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 09e07ee6d..359fb31d3 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,6 +878,8 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. +.. note:: Dictionaries (typically) provide values to :term:`template`s. + This view is configured to invoke a :term;`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From 68d16988404aec339fde1df7822c783d3ea23af6 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 11:35:34 -0500 Subject: Docs: renderers.rst: Explain typical renderer usage. --- docs/narr/renderers.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 3059aef35..235dbaf83 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -49,10 +49,14 @@ Writing View Callables Which Use a Renderer ------------------------------------------- As we've seen, a view callable needn't always return a Response object. -Instead, it may return an arbitrary Python object, with the expectation -that a :term:`renderer` will convert that object into a response instance on -your behalf. Some renderers use a templating system; other renderers use -object serialization techniques. +Instead, it may return an arbitrary Python object, with the expectation that +a :term:`renderer` will convert that object into a response instance on your +behalf. Some renderers use a templating system; other renderers use object +serialization techniques. Because renderers inject variable data into some +output (otherwise a static Response object could be returned) the renderer +must have some means of identifying the data and mapping its transformation +into the desired output. Often, as the means of providing this mapping, the +object supplied to the renderer is a Python dictionary. View configuration can vary the renderer associated with a view callable via the ``renderer`` attribute. For example, this call to -- cgit v1.2.3 From 190b5644c473286f8066c9eb430c567dfdeb4913 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 13:36:05 -0500 Subject: Docs: sessions.rst: Explain example. --- docs/narr/sessions.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 358977089..eafa9dbf9 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -99,6 +99,10 @@ example: else: return Response('Fred was not in the session') +The first time this view is invoked produces ``Fred was not in the +session``. Subsequent invocations produce ``Fred was in the +session``. + You can use a session much like a Python dictionary. It supports all dictionary methods, along with some extra attributes, and methods. -- cgit v1.2.3 From 66be39bf656a2840931603bc959e38ff95e53164 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 15:35:24 -0400 Subject: - Removed mention of ``pyramid_beaker`` from docs. Beaker is no longer maintained. Point people at ``pyramid_redis_sessions`` instead. --- docs/narr/sessions.rst | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 358977089..f8279b0a5 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -146,8 +146,6 @@ Some gotchas: you've changed sessioning data. .. index:: - single: pyramid_beaker - single: Beaker single: pyramid_redis_sessions single: session factory (alternates) @@ -156,20 +154,11 @@ Some gotchas: Using Alternate Session Factories --------------------------------- -At the time of this writing, exactly two alternate session factories -exist. - -The first is named ``pyramid_redis_sessions``. It can be downloaded from PyPI. +At the time of this writing, exactly one project-endorsed alternate session +factory exists named``pyramid_redis_sessions``. It can be downloaded from PyPI. It uses Redis as a backend. It is the recommended persistent session solution at the time of this writing. -The second is named ``pyramid_beaker``. This is a session factory that uses the -`Beaker `_ library as a backend. Beaker has -support for file-based sessions, database based sessions, and encrypted -cookie-based sessions. See `the pyramid_beaker documentation -`_ for more -information about ``pyramid_beaker``. - .. index:: single: session factory (custom) -- cgit v1.2.3 From b31cdc5beb173716235a026d264dafde12fea109 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 14:47:01 -0500 Subject: Docs: sessions.rst: Sessions only work when the client cooperates. --- docs/narr/sessions.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index eafa9dbf9..db1e0ea20 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -101,7 +101,8 @@ example: The first time this view is invoked produces ``Fred was not in the session``. Subsequent invocations produce ``Fred was in the -session``. +session``, assuming of course that the client side maintains the +session's identity across multiple requests. You can use a session much like a Python dictionary. It supports all dictionary methods, along with some extra attributes, and methods. -- cgit v1.2.3 From 5bf27497638ad607f0e42feb10145cd6720b74d3 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 15:20:59 -0500 Subject: Docs: Make statements more concreate regards renderers getting data from dictionaries. --- docs/narr/project.rst | 2 +- docs/narr/renderers.rst | 8 +++----- 2 files changed, 4 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9a1ba190d..61b6ae316 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,7 +878,7 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries (typically) provide values to :term:`template`s. +.. note:: Dictionaries provide values to :term:`template`s. This view is configured to invoke a :term;`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 235dbaf83..4046c67fa 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -52,11 +52,9 @@ As we've seen, a view callable needn't always return a Response object. Instead, it may return an arbitrary Python object, with the expectation that a :term:`renderer` will convert that object into a response instance on your behalf. Some renderers use a templating system; other renderers use object -serialization techniques. Because renderers inject variable data into some -output (otherwise a static Response object could be returned) the renderer -must have some means of identifying the data and mapping its transformation -into the desired output. Often, as the means of providing this mapping, the -object supplied to the renderer is a Python dictionary. +serialization techniques. In practice, renderers obtain application data +values from Python dictionaries so, in practice, view callables which use +renderers return Python dictionaries. View configuration can vary the renderer associated with a view callable via the ``renderer`` attribute. For example, this call to -- cgit v1.2.3 From 47e13e042c270f9ffb3ac86b294e89ec4b1fef6a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 15:27:32 -0500 Subject: Docs: project.rst: Fix markup failure just introduced. --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 61b6ae316..2acc81e17 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -880,7 +880,7 @@ This view callable function is handed a single piece of information: the .. note:: Dictionaries provide values to :term:`template`s. -This view is configured to invoke a :term;`renderer` on a template. The +This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then returns the HTML in a :term:`response`. -- cgit v1.2.3 From 4122733091d0204b22d7acedfdf985caed17f93f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 17:29:39 -0400 Subject: get rid of note that appears to be explained in the next para --- docs/narr/project.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 2acc81e17..bfd00d3a0 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,8 +878,6 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries provide values to :term:`template`s. - This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From ab2fedf7adaec0a56a69beed35312c88d7961c6c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 17:47:17 -0400 Subject: fix the docs build and get rid of stray references to Beaker --- docs/narr/project.rst | 2 +- docs/narr/sessions.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index bfd00d3a0..9451f41b1 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -977,7 +977,7 @@ named ``views`` instead of within a single ``views.py`` file, you might: - *Move* the existing ``views.py`` file to a file inside the new ``views`` directory named, say, ``blog.py``. Because the ``templates`` directory remains in the ``myproject`` package, the template :term:`asset - specification`s in ``blog.py`` must now be fully qualified with the + specification` values in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). You can then continue to add view callable functions to the ``blog.py`` diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index f4da5d82a..649d22bd2 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -159,10 +159,10 @@ Some gotchas: Using Alternate Session Factories --------------------------------- -At the time of this writing, exactly one project-endorsed alternate session -factory exists named``pyramid_redis_sessions``. It can be downloaded from PyPI. -It uses Redis as a backend. It is the recommended persistent session solution -at the time of this writing. +At the time of this writing, exactly one project-endorsed alternate session +factory exists named :term:`pyramid_redis_sessions`. It can be downloaded from +PyPI. It uses the Redis database as a backend. It is the recommended +persistent session solution at the time of this writing. .. index:: single: session factory (custom) -- cgit v1.2.3 From 96188ac4b74cb1e67cb95afdb9519ecd8934d688 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 18:56:56 -0400 Subject: rearrange the fix --- docs/narr/traversal.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index fb4adff61..454bb5620 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -128,12 +128,6 @@ Here's an example of a simple root factory class: def __init__(self, request): pass -..note:: - For the purpose of understanding traversal, and the contents within - this document, the above Root is an analogue to the default root - factory present in Pyramid. The default root factory is very simple and - not very useful unless using :term:`URL dispatch`. - Here's an example of using this root factory within startup configuration, by passing it to an instance of a :term:`Configurator` named ``config``: @@ -152,13 +146,15 @@ refer to a root factory defined in a different module. If no :term:`root factory` is passed to the :app:`Pyramid` :term:`Configurator` constructor, or if the ``root_factory`` value -specified is ``None``, a *default* root factory is used. The default +specified is ``None``, a :term:`default root factory` is used. The default root factory always returns a resource that has no child resources; it is effectively empty. Usually a root factory for a traversal-based application will be more -complicated than the above ``Root`` class; in particular it may be -associated with a database connection or another persistence mechanism. +complicated than the above ``Root`` class; in particular it may be associated +with a database connection or another persistence mechanism. The above +``Root`` class is analogous to the default root factory present in Pyramid. The +default root factory is very simple and not very useful. .. note:: -- cgit v1.2.3 From 1f7a00346411033d935bf931c206b585353f8be4 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 5 Oct 2013 00:37:09 -0500 Subject: Docs: Link from renderer narrative docs to example render_to_response call, and index the example. More fully explain the 2 examples, one with render_to_response call and one without. --- docs/narr/introduction.rst | 11 +++++++++-- docs/narr/renderers.rst | 10 ++++++---- 2 files changed, 15 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 032f4be6b..8c2acf95c 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -321,7 +321,14 @@ assertion instead that the view returns "the right stuff" in the dictionary it returns. You can write "real" unit tests instead of functionally testing all of your views. -For example, instead of: +.. index:: + pair: renderer; explicitly calling + pair: view renderer; explictly calling + +.. _example_render_to_response_call: + +For example, instead of returning a ``Response`` object from a +``render_to_response`` call: .. code-block:: python :linenos: @@ -332,7 +339,7 @@ For example, instead of: return render_to_response('myapp:templates/mytemplate.pt', {'a':1}, request=request) -You can do this: +You can return a Python dictionary: .. code-block:: python :linenos: diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 4046c67fa..b86f7298b 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -56,10 +56,12 @@ serialization techniques. In practice, renderers obtain application data values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. -View configuration can vary the renderer associated with a view callable via -the ``renderer`` attribute. For example, this call to -:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer -with a view callable: +View callables can :ref:`explicitly call +` renderers but, typically, view +configuration declares the renderer used to render a view callable's +results. This is done with the ``renderer`` attribute. For example, +this call to :meth:`~pyramid.config.Configurator.add_view` associates +the ``json`` renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From cabaa67149f95796aac35a19313ca543064a7a0b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 5 Oct 2013 00:56:39 -0500 Subject: Docs: project.rst: Hilight that dictionaries provide values to templates. --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9451f41b1..8788977c7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,6 +878,8 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. +.. note:: Dictionaries provide values to :term:`template`\s. + This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From a8cb84e04a81bcfd0236c3ff534919bb555e7ed3 Mon Sep 17 00:00:00 2001 From: BauhausSP Date: Sun, 6 Oct 2013 21:08:14 +0100 Subject: Fixed an example "from pyramid.view import view_config" instead of "from pyramid.view. import view_config" --- docs/narr/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index ca6dc565b..64343ca3e 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -150,7 +150,7 @@ do things the newer way: .. code-block:: python :linenos: - from pyramid.view. import view_config + from pyramid.view import view_config from pyramid.static import static_view myview = static_view('static', 'static', use_subpath=True) -- cgit v1.2.3 From 0f5e17a983ecb97bb0bdeb169ac775886c9e15fe Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 09:53:06 -0500 Subject: Docs: project.rst: Utilize sidebars for out-of-band text. --- docs/narr/project.rst | 58 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 24 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8788977c7..622f40d69 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -210,6 +210,12 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). +.. sidebar:: Verbose Testing + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + On UNIX: .. code-block:: text @@ -243,12 +249,6 @@ Here's sample output from a test run on UNIX: OK -.. note:: - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. @@ -684,6 +684,14 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. +.. sidebar:: Python's ``setup.py`` + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + .. index:: single: setup.py @@ -694,14 +702,6 @@ 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, packaging, and distributing your application. -.. note:: - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,6 +857,26 @@ and which returns a :term:`response`. :language: python :linenos: +.. sidebar:: Fully Interactive Development + + Because our ``development.ini`` has a ``pyramid.reload_templates = + true`` directive indicating that templates should be reloaded when + they change, you won't need to restart the application server to + see changes you make to templates. During development, this is + handy. If this directive had been ``false`` (or if the directive + did not exist), you would need to restart the application server + for each template change. For production applications, you should + set your project's ``pyramid.reload_templates`` to ``false`` to + increase template rendering speed. + + Pyramid can also dynamically reload changed Python files. For more + on this see :ref:`reloading_code` above. + + The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows + interactive access to traceback execution stack frames from the + Python interpreter. + 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``). @@ -888,16 +908,6 @@ returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. - .. index:: single: static directory -- cgit v1.2.3 From 5276ce567b1c04e3d4cadcfb7f41b135296b1d39 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 09:55:07 -0500 Subject: Docs: project.rst: Move note that tempates get values from dictionaries down a paragraph. --- docs/narr/project.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 622f40d69..fc1d473ac 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -898,13 +898,13 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries provide values to :term:`template`\s. - This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then returns the HTML in a :term:`response`. +.. note:: Dictionaries provide values to :term:`template`\s. + See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -- cgit v1.2.3 From daefb5f5009166ac9fbc3ba7fb6498d093620eec Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 10:12:14 -0500 Subject: Doc: introduction.rst: Broaden debug toolbar feature description to include other interactive development features. --- docs/narr/introduction.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 032f4be6b..64cce407a 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -176,8 +176,13 @@ static file server in production without changing any code. Example: :ref:`static_assets_section`. -Debug Toolbar -~~~~~~~~~~~~~ +Fully Interactive Development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When developing a Pyramid application a variety of interactive features are +available. Pyramid will automatically utilize changed templates when +rendering pages and automatically restart the application to incorporate +changed python code. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 6461f60320106b5114bb7f226959c7d7f2995ec2 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 11:26:22 -0500 Subject: Docs: introduction.rst: Improve wording. --- docs/narr/introduction.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 64cce407a..816199038 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -179,10 +179,10 @@ Example: :ref:`static_assets_section`. Fully Interactive Development ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When developing a Pyramid application a variety of interactive features are -available. Pyramid will automatically utilize changed templates when -rendering pages and automatically restart the application to incorporate -changed python code. +When developing a Pyramid application a variety of interactive +features are available. Pyramid can automatically utilize changed +templates when rendering pages and automatically restart the +application to incorporate changed python code. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 70b05dfaea547fea328a7054acd921f02be34a87 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:06:15 -0500 Subject: Docs: renders.rst: Use punctuation to make sentence simpler. --- docs/narr/renderers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index b86f7298b..49f834ecb 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -57,7 +57,7 @@ values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. View callables can :ref:`explicitly call -` renderers but, typically, view +` renderers; but typically view configuration declares the renderer used to render a view callable's results. This is done with the ``renderer`` attribute. For example, this call to :meth:`~pyramid.config.Configurator.add_view` associates -- cgit v1.2.3 From 77497acef17d5e5996ac231bf8ac9b679b291316 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:10:18 -0500 Subject: Docs: renders.rst: Break sentence into two to simplify. --- docs/narr/renderers.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 49f834ecb..b542e42a2 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -57,11 +57,12 @@ values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. View callables can :ref:`explicitly call -` renderers; but typically view -configuration declares the renderer used to render a view callable's -results. This is done with the ``renderer`` attribute. For example, -this call to :meth:`~pyramid.config.Configurator.add_view` associates -the ``json`` renderer with a view callable: +` renderers, but they typically +don't. Instead view configuration declares the renderer used to +render a view callable's results. This is done with the ``renderer`` +attribute. For example, this call to +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` +renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From 0681d5798574d5f3ed644bf56086208c8571e0b9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:12:27 -0500 Subject: Docs: renders.rst: Make sentences short per IRC chat with committers. --- docs/narr/renderers.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index b542e42a2..7c25386f5 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -56,13 +56,11 @@ serialization techniques. In practice, renderers obtain application data values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. -View callables can :ref:`explicitly call -` renderers, but they typically -don't. Instead view configuration declares the renderer used to -render a view callable's results. This is done with the ``renderer`` -attribute. For example, this call to -:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` -renderer with a view callable: +View callables can :ref:`explicitly call ` +renderers. Typically view configuration declares the renderer used to render +a view callable's results. This is done with the ``renderer`` attribute. +For example, this call to :meth:`~pyramid.config.Configurator.add_view` +associates the ``json`` renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From a26d09f291bdf4f9c7853b1dbfc9643a678a7b94 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:29:31 -0500 Subject: Docs: renders.rst: Make sentences that everybody's happy with. --- docs/narr/renderers.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 7c25386f5..740c81555 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -57,10 +57,11 @@ values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. View callables can :ref:`explicitly call ` -renderers. Typically view configuration declares the renderer used to render -a view callable's results. This is done with the ``renderer`` attribute. -For example, this call to :meth:`~pyramid.config.Configurator.add_view` -associates the ``json`` renderer with a view callable: +renderers, but typically don't. Instead view configuration declares the +renderer used to render a view callable's results. This is done with the +``renderer`` attribute. For example, this call to +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` +renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From 56170f30f6cd1d4268d9e5b0cd24a75c645ab0ca Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 21:00:26 -0500 Subject: Docs: project.rst: Reword template reload note per Steve Piercy's suggestions. Take care to retain the thought that the defaults setup by the scaffold cause automatic template reload. This patch should be applied before the docs_dict_note branch. --- docs/narr/project.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9451f41b1..0de46c806 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -886,15 +886,16 @@ returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. +.. note:: ``development.ini`` has a setting that controls how templates are + reloaded: ``pyramid.reload_templates``. + + - A setting of ``True`` (as in the scaffold ``development.ini``) + automatically reloads changed templates without a server restart. This + is convenient while developing but slows template rendering speed. + + - A setting of ``False`` (the default) requires a server restart to + integrate template changes. Production applications should set + ``pyramid.reload_templates = False``. .. index:: single: static directory -- cgit v1.2.3 From 8e1e6914945a5a3d05f49f0e32b7152182b23767 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 22:20:26 -0500 Subject: Docs: introduction.rst: Note that printf() works. --- docs/narr/introduction.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 9ec26f276..b60934ebb 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -182,7 +182,8 @@ Fully Interactive Development When developing a Pyramid application a variety of interactive features are available. Pyramid can automatically utilize changed templates when rendering pages and automatically restart the -application to incorporate changed python code. +application to incorporate changed python code. Plain old ``printf()`` +calls used for debugging can display to a console. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 5ded35a5d057eb6188d6f80c47593ec934833d47 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:32:14 -0700 Subject: - straighten out difference between content and its presentation, re: admonitions of note, seealse, sidebar --- docs/narr/project.rst | 79 +++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 46 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4397c09b..fcce9fac4 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -146,7 +146,7 @@ puts his projects in ``C:\projects``. .. warning:: - You’ll need to avoid using ``pcreate`` to create a project with the same + You'll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you should avoid using the names ``site`` or ``test``, both of which conflict with Python standard library packages. You should also avoid @@ -210,12 +210,6 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). -.. sidebar:: Verbose Testing - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - On UNIX: .. code-block:: text @@ -253,6 +247,12 @@ The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. +.. note:: + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + .. index:: single: running an application single: pserve @@ -684,14 +684,6 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. -.. sidebar:: Python's ``setup.py`` - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - .. index:: single: setup.py @@ -702,6 +694,14 @@ 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, packaging, and distributing your application. +.. note:: + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,26 +857,6 @@ and which returns a :term:`response`. :language: python :linenos: -.. sidebar:: Fully Interactive Development - - Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to - increase template rendering speed. - - Pyramid can also dynamically reload changed Python files. For more - on this see :ref:`reloading_code` above. - - The :ref:`debug_toolbar` provides interactive access to your - application's internals and, should an exception occur, allows - interactive access to traceback execution stack frames from the - Python interpreter. - 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``). @@ -905,20 +885,27 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. -See :ref:`views_which_use_a_renderer` for more information about how views, -renderers, and templates relate and cooperate. - .. note:: ``development.ini`` has a setting that controls how templates are - reloaded: ``pyramid.reload_templates``. - - - A setting of ``True`` (as in the scaffold ``development.ini``) - automatically reloads changed templates without a server restart. This - is convenient while developing but slows template rendering speed. - - - A setting of ``False`` (the default) requires a server restart to - integrate template changes. Production applications should set + reloaded, ``pyramid.reload_templates``. + + - When set to ``True`` (as in the scaffold ``development.ini``) changed + templates automatically reload without a server restart. This is + convenient while developing, but slows template rendering speed. + + - When set to ``False`` (the default value), changing templates requires + a server restart to reload them. Production applications should use ``pyramid.reload_templates = False``. +.. seealso:: See also :ref:`views_which_use_a_renderer` for more information + about how views, renderers, and templates relate and cooperate. + +.. seealso:: Pyramid can also dynamically reload changed Python files. For + more on this see :ref:`reloading_code`. + +.. seealso:: The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows interactive + access to traceback execution stack frames from the Python interpreter. + .. index:: single: static directory -- cgit v1.2.3 From d84407421d1830ed726bcc280b3de112aca701e7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:40:10 -0700 Subject: wrap to 79 --- docs/narr/introduction.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index b60934ebb..ece720a97 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -179,11 +179,11 @@ Example: :ref:`static_assets_section`. Fully Interactive Development ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When developing a Pyramid application a variety of interactive -features are available. Pyramid can automatically utilize changed -templates when rendering pages and automatically restart the -application to incorporate changed python code. Plain old ``printf()`` -calls used for debugging can display to a console. +When developing a Pyramid application, several interactive features are +available. Pyramid can automatically utilize changed templates when rendering +pages and automatically restart the application to incorporate changed python +code. Plain old ``printf()`` calls used for debugging can display to a +console. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and @@ -790,7 +790,7 @@ automate some of the tedium away: for method in ('GET', 'POST', 'HEAD'): view = getattr(module, 'xhr_%s_view' % method, None) if view is not None: - config.add_view(view, route_name='xhr_route', xhr=True, + config.add_view(view, route_name='xhr_route', xhr=True, permission='view', request_method=method) config = Configurator() -- cgit v1.2.3 From 716bdf37573ee8ef295ac1d01a1e8ff96c4c0f43 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:55:30 -0700 Subject: - use clearer subject --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fcce9fac4..8b7c24725 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -984,9 +984,9 @@ named ``views`` instead of within a single ``views.py`` file, you might: can be empty. This just tells Python that the ``views`` directory is a *package*.) -- *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. Because the ``templates`` directory - remains in the ``myproject`` package, the template :term:`asset +- *Move* the content from the existing ``views.py`` file to a file inside the + new ``views`` directory named, say, ``blog.py``. Because the ``templates`` + directory remains in the ``myproject`` package, the template :term:`asset specification` values in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). -- cgit v1.2.3 From eb3b27df0a35088f631680d7f467680662f17bac Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 8 Oct 2013 06:17:13 -0500 Subject: Docs: project.rst: Printf()s can be used for debugging. Output goes to the server console. The main point of the second sentence is to setup the reader with mental context for the 3rd sentence, so that the 3rd sentence sinks in. Likewise, the parenthetical in the second sentence about server startup messages gives the reader some clue as to what the rest of the sentence it talking about. I suspect that some readers won't know what a console is, and the rest will be confused by a server run on a console. --- docs/narr/project.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8b7c24725..a454573f0 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -259,6 +259,8 @@ single sample test exists. single: reload single: startup +.. _running_the_project_application: + Running The Project Application ------------------------------- @@ -600,6 +602,8 @@ server which listens on TCP port 6543. It is configured to listen on all interfaces (``0.0.0.0``). This means that any remote system which has TCP access to your system can see your Pyramid application. +.. _MyProject_ini_logging: + The sections that live between the markers ``# Begin logging configuration`` and ``# End logging configuration`` represent Python's standard library :mod:`logging` module configuration for your application. The sections @@ -885,6 +889,14 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. +.. note:: When the application is run with the scaffold's :ref:`default + development.ini ` configuration :ref:`logging is setup + ` to aid debugging. Should an exception be raised, + uncaught tracebacks are displayed, after the startup messages, on :ref:`the + console running the server `. + Conveniently, ``printf()``\s inserted into the application for debugging + also send output to this console. + .. note:: ``development.ini`` has a setting that controls how templates are reloaded, ``pyramid.reload_templates``. -- cgit v1.2.3 From fd99b0e53835dd7463986c4d705e8de06be7dbe6 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 8 Oct 2013 09:16:10 -0500 Subject: Docs: project.rst: Oops, print(), not printf(). --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index a454573f0..9a15649d7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -894,7 +894,7 @@ returns the HTML in a :term:`response`. ` to aid debugging. Should an exception be raised, uncaught tracebacks are displayed, after the startup messages, on :ref:`the console running the server `. - Conveniently, ``printf()``\s inserted into the application for debugging + Conveniently, ``print()``\s inserted into the application for debugging also send output to this console. .. note:: ``development.ini`` has a setting that controls how templates are -- cgit v1.2.3 From 2004173e4f1614b8eb9cc3534ec3117c736ff009 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 8 Oct 2013 09:37:39 -0500 Subject: Docs: introduction.rst: Beaker -> Redis. --- docs/narr/introduction.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index ece720a97..4e705b8b1 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -418,12 +418,12 @@ Sessions Pyramid has built-in HTTP sessioning. This allows you to associate data with otherwise anonymous users between requests. Lots of systems do this. But -Pyramid also allows you to plug in your own sessioning system by creating -some code that adheres to a documented interface. Currently there is a -binding package for the third-party Beaker sessioning system that does exactly -this. But if you have a specialized need (perhaps you want to store your -session data in MongoDB), you can. You can even switch between -implementations without changing your application code. +Pyramid also allows you to plug in your own sessioning system by creating some +code that adheres to a documented interface. Currently there is a binding +package for the third-party Redis sessioning system that does exactly this. +But if you have a specialized need (perhaps you want to store your session data +in MongoDB), you can. You can even switch between implementations without +changing your application code. Example: :ref:`sessions_chapter`. -- cgit v1.2.3 From 4bc489d00bcb6013db1e9da00c3c16809eeb90fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 8 Oct 2013 11:17:18 -0700 Subject: print() not printf() --- docs/narr/introduction.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index ece720a97..bb2d85e94 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -180,10 +180,9 @@ Fully Interactive Development ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When developing a Pyramid application, several interactive features are -available. Pyramid can automatically utilize changed templates when rendering +available. Pyramid can automatically utilize changed templates when rendering pages and automatically restart the application to incorporate changed python -code. Plain old ``printf()`` calls used for debugging can display to a -console. +code. Plain old ``print()`` calls used for debugging can display to a console. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 6db4eb3a5fe625918c52b40ed669f1b55343abf9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 14 Oct 2013 12:42:17 +0200 Subject: add note about custom args to python when using command-line scripts --- docs/narr/commandline.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 58b9bdd21..0984b4daf 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -474,6 +474,17 @@ input of the ``prequest`` process is used as the ``POST`` body:: $ $VENV/bin/prequest -mPOST development.ini / < somefile +Using Custom Arguments to Python when Running ``p*`` Scripts +------------------------------------------------------------ + +.. versionadded:: 1.5 + +Each of Pyramid's console scripts (``pserve``, ``pviews``, etc) can be run +directly using ``python -m``, allowing custom arguments to be sent to the +python interpreter at runtime. For example:: + + python -3 -m pyramid.scripts.pserve development.ini + Showing All Installed Distributions and their Versions ------------------------------------------------------ -- cgit v1.2.3 From 3acee31f86bcde8abbb4e63715afc5ca67976eaf Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 17 Oct 2013 13:32:49 -0500 Subject: fix documentation for csrf checking --- docs/narr/sessions.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 649d22bd2..f33bc6132 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -363,25 +363,27 @@ Or, include it as a header in a jQuery AJAX request: The handler for the URL that receives the request should then require that the correct CSRF token is supplied. -Using the ``session.check_csrf_token`` Method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Checking CSRF Tokens Manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In request handling code, you can check the presence and validity of a CSRF -token with ``session.check_csrf_token(request)``. If the token is valid, -it will return True, otherwise it will raise ``HTTPBadRequest``. +token with :func:`pyramid.session.check_csrf_token(request)``. If the token is +valid, it will return ``True``, otherwise it will raise ``HTTPBadRequest``. +Optionally, you can specify ``raises=False`` to have the check return ``False`` +instead of raising an exception. By default, it checks for a GET or POST parameter named ``csrf_token`` or a header named ``X-CSRF-Token``. .. code-block:: python - def myview(request): - session = request.session + from pyramid.session import check_csrf_token + def myview(request): # Require CSRF Token - session.check_csrf_token(request): + check_csrf_token(request) - ... + # ... .. index:: single: session.new_csrf_token -- cgit v1.2.3