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') 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 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') 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') 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') 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') 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 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') 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') 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') 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') 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/glossary.rst | 9 ++++++++- docs/narr/project.rst | 2 +- docs/narr/sessions.rst | 8 ++++---- docs/quick_tour.rst | 7 +++---- 4 files changed, 16 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 7dc69c7c4..398f945a4 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1009,7 +1009,8 @@ Glossary Green Unicorn Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under - Python 2.6+ or Python 3.1+. 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 @@ -1021,3 +1022,9 @@ Glossary A Python :term:`distribution` that uses Pyramid's extensibility to plug into a Pyramid application and provide extra, configurable services. + + pyramid_redis_sessions + A package by Eric Rasmussen which allows you to store Pyramid session + data in a Redis database. See + https://pypi.python.org/pypi/pyramid_redis_sessions for more information. + 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) diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 98584e608..2db18c8a7 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -729,8 +729,8 @@ that requires semi-permanent data to be saved. For example, a shopping cart. This is called a :term:`session`. Pyramid has basic built-in support for sessions, with add-ons such as -*Beaker* (or your own custom sessioning engine) that provide richer -session support. Let's take a look at the +``pyramid_redis_sessions`` (or your own custom sessioning engine) that provide +richer session support. Let's take a look at the :doc:`built-in sessioning support <../narr/sessions>`. In our ``__init__.py`` we first import the kind of sessioning we want: @@ -768,8 +768,7 @@ Jinja2 template: .. seealso:: See Also: :ref:`Quick Tutorial Sessions `, :ref:`sessions_chapter`, :ref:`flash_messages`, - :ref:`session_module`, and - :ref:`Beaker sessioning middleware ` + :ref:`session_module`, and :term:`pyramid_redis_sessions`. Databases ========= -- 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/glossary.rst | 23 ++++++++++++++--------- docs/narr/traversal.rst | 14 +++++--------- 2 files changed, 19 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 398f945a4..406b81778 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -505,15 +505,20 @@ Glossary available as its ``__parent__`` attribute. root factory - The "root factory" of a :app:`Pyramid` application is called - on every request sent to the application. The root factory - returns the traversal root of an application. It is - conventionally named ``get_root``. An application may supply a - root factory to :app:`Pyramid` during the construction of a - :term:`Configurator`. If a root factory is not supplied, the - application uses a default root object. Use of the default root - object is useful in application which use :term:`URL dispatch` for - all URL-to-view code mappings. + The "root factory" of a :app:`Pyramid` application is called on every + request sent to the application. The root factory returns the traversal + root of an application. It is conventionally named ``get_root``. An + application may supply a root factory to :app:`Pyramid` during the + construction of a :term:`Configurator`. If a root factory is not + supplied, the application creates a default root object using the + :term:`default root factory`. + + default root factory + If an application does not register a :term:`root factory` at Pyramid + configuration time, a *default* root factory is used to created the + default root object. Use of the default root object is useful in + application which use :term:`URL dispatch` for all URL-to-view code + mappings, and does not (knowingly) use traversal otherwise. SQLAlchemy `SQLAlchemy `_ is an object 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