diff options
Diffstat (limited to 'docs/tutorials')
28 files changed, 103 insertions, 103 deletions
diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst index ebb0a9681..537f8accf 100644 --- a/docs/tutorials/bfg/index.rst +++ b/docs/tutorials/bfg/index.rst @@ -4,17 +4,17 @@ .. _converting_a_bfg_app: -Converting a :mod:`repoze.bfg` Application to :mod:`pyramid` +Converting a :mod:`repoze.bfg` Application to :app:`Pyramid` ============================================================ -Prior iterations of :mod:`pyramid` were released as a package named +Prior iterations of :app:`Pyramid` were released as a package named :mod:`repoze.bfg`. :mod:`repoze.bfg` users are encouraged to upgrade -their deployments to :mod:`pyramid`, as, after the first final release -of :mod:`pyramid`, further feature development on :mod:`repoze.bfg` +their deployments to :app:`Pyramid`, as, after the first final release +of :app:`Pyramid`, further feature development on :mod:`repoze.bfg` will cease. Most existing :mod:`repoze.bfg` applications can be converted to a -:mod:`pyramid` application in a completely automated fashion. +:app:`Pyramid` application in a completely automated fashion. However, if your application depends on packages which are not "core" parts of :mod:`repoze.bfg` but which nonetheless have ``repoze.bfg`` in their names (e.g. ``repoze.bfg.skins``, @@ -24,11 +24,11 @@ there will be a ``pyramid_jinja2`` package, which can be used instead of ``repoze.bfg.jinja2``. If an analogue does not seem to exist for a ``repoze.bfg`` add-on package that your application uses, please email the `Pylons-devel <http://groups.google.com/group/pylons-devel>`_ -maillist; we'll convert the package to a :mod:`pyramid` analogue for +maillist; we'll convert the package to a :app:`Pyramid` analogue for you. Here's how to convert a :mod:`repoze.bfg` application to a -:mod:`pyramid` application: +:app:`Pyramid` application: #. Ensure that your application works under :mod:`repoze.bfg` *version 1.3 or better*. See @@ -52,8 +52,8 @@ Here's how to convert a :mod:`repoze.bfg` application to a ``bfgenv`` above will be the virtualenv into which you've installed :mod:`repoze.bfg` 1.3. -#. Install :mod:`pyramid` into a *separate* virtualenv as per the - instructions in :ref:`installing_chapter`. The :mod:`pyramid` +#. Install :app:`Pyramid` into a *separate* virtualenv as per the + instructions in :ref:`installing_chapter`. The :app:`Pyramid` virtualenv should be separate from the one you've used to install :mod:`repoze.bfg`. A quick way to do this: @@ -74,8 +74,8 @@ Here's how to convert a :mod:`repoze.bfg` application to a $ svn co http://my.server/my/bfg/application/trunk bfgapp #. Use the ``bfg2pyramid`` script present in the ``bin`` directory of - the :mod:`pyramid` virtualenv to convert all :mod:`repoze.bfg` - Python import statements into compatible :mod:`pyramid` import + the :app:`Pyramid` virtualenv to convert all :mod:`repoze.bfg` + Python import statements into compatible :app:`Pyramid` import statements. ``bfg2pyramid`` will also fix ZCML directive usages of common :mod:`repoze.bfg` directives. You invoke ``bfg2pyramid`` by passing it the *path* of the copy of your application. The path @@ -88,10 +88,10 @@ Here's how to convert a :mod:`repoze.bfg` application to a $ ~/pyramidenv/bfg2pyramid /tmp/bfgapp ``bfg2pyramid`` will convert the following :mod:`repoze.bfg` - application aspects to :mod:`pyramid` compatible analogues: + application aspects to :app:`Pyramid` compatible analogues: - Python ``import`` statements naming :mod:`repoze.bfg` APIs will - be converted to :mod:`pyramid` compatible ``import`` statements. + be converted to :app:`Pyramid` compatible ``import`` statements. Every Python file beneath the top-level path will be visited and converted recursively, except Python files which live in directories which start with a ``.`` (dot). @@ -107,7 +107,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a - ZCML files which contain directives that have attributes which name a ``repoze.bfg`` API module or attribute of an API module (e.g. ``context="repoze.bfg.exceptions.NotFound"``) will be - converted to :mod:`pyramid` compatible ZCML attributes + converted to :app:`Pyramid` compatible ZCML attributes (e.g. ``context="pyramid.exceptions.NotFound``). Every ZCML file beneath the top-level path (files ending with ``.zcml``) will be visited and converted recursively, except ZCML files which live @@ -137,11 +137,11 @@ Here's how to convert a :mod:`repoze.bfg` application to a #. Convert any ``install_requires`` dependencies your application has on other add-on packages which have ``repoze.bfg`` in their names - to :mod:`pyramid` compatible analogues (e.g. ``repoze.bfg.jinja2`` + to :app:`Pyramid` compatible analogues (e.g. ``repoze.bfg.jinja2`` should be replaced with ``pyramid_jinja2``). You may need to adjust configuration options and/or imports in your :mod:`repoze.bfg` application after replacing these add-ons. Read - the documentation of the :mod:`pyramid` add-on package for + the documentation of the :app:`Pyramid` add-on package for information. #. *Only if you use ZCML and add-ons which use ZCML*: The default @@ -176,7 +176,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a <bfg:failingtag attr="foo"/> </configure> -#. Retest your application using :mod:`pyramid`. This might be as +#. Retest your application using :app:`Pyramid`. This might be as easy as: .. code-block:: bash diff --git a/docs/tutorials/catalog/index.rst b/docs/tutorials/catalog/index.rst index 410016476..43b078edc 100644 --- a/docs/tutorials/catalog/index.rst +++ b/docs/tutorials/catalog/index.rst @@ -1,6 +1,6 @@ .. _catalog_tutorial: -Using :mod:`repoze.catalog` Within :mod:`pyramid` +Using :mod:`repoze.catalog` Within :app:`Pyramid` ================================================= :mod:`repoze.catalog` is a ZODB-based system that can be used to index diff --git a/docs/tutorials/cmf/actions.rst b/docs/tutorials/cmf/actions.rst index 0de6d580d..8af8e5fd4 100644 --- a/docs/tutorials/cmf/actions.rst +++ b/docs/tutorials/cmf/actions.rst @@ -8,7 +8,7 @@ In CMF, the "actions tool" along with "action providers" create an extensible mechanism to show links in the CMF management UI that invoke a particular behavior or which show a particular template. -:mod:`pyramid` itself has no such concept, and no package provides +:app:`Pyramid` itself has no such concept, and no package provides a direct replacement. Actions are such a generic concept that it's simple to reimplement action-like navigation in a different way within any given application. For example, a module-scope global dictionary diff --git a/docs/tutorials/cmf/catalog.rst b/docs/tutorials/cmf/catalog.rst index 11a9483a6..d5e9534ae 100644 --- a/docs/tutorials/cmf/catalog.rst +++ b/docs/tutorials/cmf/catalog.rst @@ -8,7 +8,7 @@ The main feature of the CMF catalog is that it filters search results from the Zope 2 "catalog" based on the requesting user's ability to view a particular cataloged object. -:mod:`pyramid` itself has no cataloging facility, but an addon +:app:`Pyramid` itself has no cataloging facility, but an addon package named :term:`repoze.catalog` offers similar functionality. Creating an Allowed Index diff --git a/docs/tutorials/cmf/content.rst b/docs/tutorials/cmf/content.rst index a8b2b8124..85e5b5fbc 100644 --- a/docs/tutorials/cmf/content.rst +++ b/docs/tutorials/cmf/content.rst @@ -10,7 +10,7 @@ code which generates an instance of that content. It is possible to construct and enumerate content types using APIs defined on the types tool. -:mod:`pyramid` itself has no such concept, but an addon package named +:app:`Pyramid` itself has no such concept, but an addon package named :term:`repoze.lemonade` has a barebones replacement. Factory Type Information @@ -22,7 +22,7 @@ initial view name, a factory, and a number of security settings with a type name. Each type information object knows how to manufacture content objects that match its type. -:mod:`pyramid` certainly enforces none of these concepts in any +:app:`Pyramid` certainly enforces none of these concepts in any particular way, but :term:`repoze.lemonade` does. ``repoze.lemonade`` Content @@ -51,7 +51,7 @@ of helper functions which allow you to: content-agnostic unit tests or if you need to get an enumerated subset of content type information to aid in UI generation. That said, this *is* a tutorial about how to - get CMF-like features in :mod:`pyramid`, so we'll assume + get CMF-like features in :app:`Pyramid`, so we'll assume the pattern is useful to readers. See the `repoze.lemonade package diff --git a/docs/tutorials/cmf/index.rst b/docs/tutorials/cmf/index.rst index 65ad99551..94c73af8e 100644 --- a/docs/tutorials/cmf/index.rst +++ b/docs/tutorials/cmf/index.rst @@ -1,21 +1,21 @@ -Converting an Existing Zope/CMF Application to :mod:`pyramid` +Converting an Existing Zope/CMF Application to :app:`Pyramid` ================================================================ The Zope `Content Management Framework <http://www.zope.org/Products/CMF/>`_ (aka CMF) is a layer on top of :term:`Zope` 2 that provides facilities for creating content-driven websites. It's reasonably easy to convert a modern Zope/CMF -application to :mod:`pyramid`. +application to :app:`Pyramid`. -The main difference between CMF and :mod:`pyramid` is that -:mod:`pyramid` does not advertise itself as a system into which you +The main difference between CMF and :app:`Pyramid` is that +:app:`Pyramid` does not advertise itself as a system into which you can plug arbitrary "packages" that extend a system-supplied management user interface. You *could* build a CMF-like layer on top of -:mod:`pyramid` (as CMF is built on Zope) but none currently exists. +:app:`Pyramid` (as CMF is built on Zope) but none currently exists. For those sorts of high-extensibility, highly-regularized-UI systems, CMF is still the better choice. -:mod:`pyramid` (and other more lightweight systems) is often a +:app:`Pyramid` (and other more lightweight systems) is often a better choice when you're building the a user interface from scratch, which often happens when the paradigms of some CMF-provided user interface don't match the requirements of an application very closely. diff --git a/docs/tutorials/cmf/skins.rst b/docs/tutorials/cmf/skins.rst index 7ec3b1be6..676a076b3 100644 --- a/docs/tutorials/cmf/skins.rst +++ b/docs/tutorials/cmf/skins.rst @@ -12,7 +12,7 @@ products often provide skin layers that are activated within a particular skin to provide the site with additional features. To override static resources using a "search path" much like a set of -skin layers, :mod:`pyramid` provides the concept of +skin layers, :app:`Pyramid` provides the concept of :term:`resource` overrides. See :ref:`overriding_resources_section` for more information about resource overrides. diff --git a/docs/tutorials/cmf/workflow.rst b/docs/tutorials/cmf/workflow.rst index 35cf552d2..cc70d771a 100644 --- a/docs/tutorials/cmf/workflow.rst +++ b/docs/tutorials/cmf/workflow.rst @@ -7,7 +7,7 @@ Workflow In CMF, the "workflow tool" allows developers to design state machines which imply transition between content states. -:mod:`pyramid` itself has no such concept, but the +:app:`Pyramid` itself has no such concept, but the :term:`repoze.workflow` package provides a simple state machine implementation that can act as a barebones workflow tool. See its documentation for more information. diff --git a/docs/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst index 746736453..a2b190a31 100644 --- a/docs/tutorials/gae/index.rst +++ b/docs/tutorials/gae/index.rst @@ -1,9 +1,9 @@ .. _appengine_tutorial: -Running :mod:`pyramid` on Google's App Engine +Running :app:`Pyramid` on Google's App Engine ================================================ -It is possible to run a :mod:`pyramid` application on Google's `App +It is possible to run a :app:`Pyramid` application on Google's `App Engine <http://code.google.com/appengine/>`_. Content from this tutorial was contributed by YoungKing, based on the `"appengine-monkey" tutorial for Pylons @@ -43,18 +43,18 @@ system. ``pyramidapp/app/`` which is the directory you will upload to appengine. -#. Install :mod:`pyramid` into the virtualenv +#. Install :app:`Pyramid` into the virtualenv .. code-block:: text $ cd pyramidapp/ $ bin/easy_install pyramid - This will install :mod:`pyramid` in the environment. + This will install :app:`Pyramid` in the environment. #. Create your application - We'll use the standard way to create a :mod:`pyramid` + We'll use the standard way to create a :app:`Pyramid` application, but we'll have to move some files around when we are done. The below commands assume your current working directory is the ``pyramidapp`` virtualenv directory you created in the third step @@ -222,7 +222,7 @@ packages. You can zip a package like so: $ bin/pip zip pytz-2009g-py2.5.egg -Note that it requires the whole egg file name. For a :mod:`pyramid` app, the +Note that it requires the whole egg file name. For a :app:`Pyramid` app, the following packages are good candidates to be zipped. - Chameleon diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index 8b429a0c8..ff5aaea18 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -1,6 +1,6 @@ .. _modwsgi_tutorial: -Running a :mod:`pyramid` Application under ``mod_wsgi`` +Running a :app:`Pyramid` Application under ``mod_wsgi`` ========================================================== :term:`mod_wsgi` is an Apache module developed by Graham Dumpleton. @@ -8,15 +8,15 @@ It allows :term:`WSGI` programs to be served using the Apache web server. This guide will outline broad steps that can be used to get a -:mod:`pyramid` application running under Apache via ``mod_wsgi``. +:app:`Pyramid` application running under Apache via ``mod_wsgi``. This particular tutorial was developed under Apple's Mac OS X platform (Snow Leopard, on a 32-bit Mac), but the instructions should be largely the same for all systems, delta specific path information for commands and files. .. note:: Unfortunately these instructions almost certainly won't work - for deploying a :mod:`pyramid` application on a Windows system - using ``mod_wsgi``. If you have experience with :mod:`pyramid` + for deploying a :app:`Pyramid` application on a Windows system + using ``mod_wsgi``. If you have experience with :app:`Pyramid` and ``mod_wsgi`` on Windows systems, please help us document this experience by submitting documentation to the `mailing list <http://lists.repoze.org/listinfo/repoze-dev>`_. @@ -49,17 +49,17 @@ commands and files. $ cd modwsgi $ /usr/local/bin/virtualenv --no-site-packages env -#. Install :mod:`pyramid` into the newly created virtualenv: +#. Install :app:`Pyramid` into the newly created virtualenv: .. code-block:: text $ cd ~/modwsgi/env $ bin/easy_install pyramid -#. Create and install your :mod:`pyramid` application. For the +#. Create and install your :app:`Pyramid` application. For the purposes of this tutorial, we'll just be using the ``bfg_starter`` application as a baseline application. Substitute your existing - :mod:`pyramid` application as necessary if you already have + :app:`Pyramid` application as necessary if you already have one. .. code-block:: text @@ -122,7 +122,7 @@ commands and files. :term:`mod_wsgi` has many knobs and a great variety of deployment modes. This is just one representation of how you might use it to -serve up a :mod:`pyramid` application. See the `mod_wsgi +serve up a :app:`Pyramid` application. See the `mod_wsgi configuration documentation <http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines>`_ for more in-depth configuration information. diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index e63a610c2..062c553b5 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -7,7 +7,7 @@ view, edit, and add pages to our wiki. For purposes of demonstration we'll change our application to allow people whom are members of a *group* named ``group:editors`` to add and edit wiki pages but we'll continue allowing anyone with access to the server to view pages. -:mod:`pyramid` provides facilities for *authorization* and +:app:`Pyramid` provides facilities for *authorization* and *authentication*. We'll make use of both features to provide security to our application. @@ -19,7 +19,7 @@ The source code for this tutorial stage can be browsed via Configuring a ``pyramid`` Authentication Policy -------------------------------------------------- -For any :mod:`pyramid` application to perform authorization, we +For any :app:`Pyramid` application to perform authorization, we need to add a ``security.py`` module and we'll need to change our :term:`application registry` to add an :term:`authentication policy` and a :term:`authorization policy`. @@ -31,7 +31,7 @@ We'll change our ``configure.zcml`` file to enable an ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable declarative security checking. We'll also add a new view stanza, which specifies a :term:`forbidden view`. This configures our -login view to show up when :mod:`pyramid` detects that a view +login view to show up when :app:`Pyramid` detects that a view invocation can not be authorized. When you're done, your ``configure.zcml`` will look like so: @@ -146,7 +146,7 @@ Giving Our Root Model Object an ACL ----------------------------------- We need to give our root model object an :term:`ACL`. This ACL will -be sufficient to provide enough information to the :mod:`pyramid` +be sufficient to provide enough information to the :app:`Pyramid` security machinery to challenge a user who doesn't have appropriate credentials when he attempts to invoke the ``add_page`` or ``edit_page`` views. @@ -171,7 +171,7 @@ class scope to our ``Wiki`` class: 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 :mod:`pyramid` applications. We +level security" can be achieved in :app:`Pyramid` applications. We actually only need *one* ACL for the entire system, however, because our security requirements are simple, so this feature is not demonstrated. diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst index a7f9d1e82..e49407b70 100644 --- a/docs/tutorials/wiki/background.rst +++ b/docs/tutorials/wiki/background.rst @@ -2,8 +2,8 @@ Background ========== -This version of the :mod:`pyramid` wiki tutorial presents a -:mod:`pyramid` application that uses technologies which will be +This version of the :app:`Pyramid` wiki tutorial presents a +:app:`Pyramid` application that uses technologies which will be familiar to someone with :term:`Zope` experience. It uses :term:`ZODB` as a persistence mechanism and :term:`traversal` to map URLs to code. It can also be followed by people without any prior @@ -13,6 +13,6 @@ 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* he will need a Windows system of any kind. -This tutorial targets :mod:`pyramid` version 1.0. +This tutorial targets :app:`Pyramid` version 1.0. Have fun! diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index d129ff7ec..85cfc825b 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 ``pyramid_zodb`` template are basic, but they provide a good orientation for the high-level patterns common -to most :term:`traversal` -based :mod:`pyramid` (and :term:`ZODB` +to most :term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects. The source code for this tutorial stage can be browsed via @@ -101,7 +101,7 @@ following: Content Models with ``models.py`` --------------------------------- -:mod:`pyramid` often uses the word :term:`model` when talking about +:app:`Pyramid` often uses the word :term:`model` when talking about content resources arranged in the hierarchical *object graph* consulted by :term:`traversal`. The ``models.py`` file is where the ``pyramid_zodb`` Paster template put the classes that implement our @@ -124,7 +124,7 @@ Here is the source for ``models.py``: #. *Lines 6-12*. ``appmaker`` is used to return the *application root* object. It is called on *every request* to the - :mod:`pyramid` application. It also performs bootstrapping by + :app:`Pyramid` application. It also performs bootstrapping by *creating* an application root (inside the ZODB root object) if one does not already exist. diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst index 3fa72dd87..097485047 100644 --- a/docs/tutorials/wiki/definingmodels.rst +++ b/docs/tutorials/wiki/definingmodels.rst @@ -57,7 +57,7 @@ Our ``Wiki`` class should also have a ``__name__`` attribute set to ``None`` at class scope, and should have a ``__parent__`` attribute set to ``None`` at class scope as well. If a model has a ``__parent__`` attribute of ``None`` in a traversal-based -:mod:`pyramid` application, it means that it's the :term:`root` +:app:`Pyramid` application, it means that it's the :term:`root` model. The ``__name__`` of the root model is also always ``None``. Then we'll add a ``Page`` class. This class should inherit from the diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 797eee0d9..bbda3d45c 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -2,16 +2,16 @@ Defining Views ============== -A :term:`view callable` in a traversal-based :mod:`pyramid` +A :term:`view callable` in a traversal-based :app:`Pyramid` application is typically a simple Python function that accepts two parameters: :term:`context`, and :term:`request`. A view callable is assumed to return a :term:`response` object. -.. note:: A :mod:`pyramid` view can also be defined as callable +.. note:: A :app:`Pyramid` view can also be defined as callable which accepts *one* arguments: a :term:`request`. You'll see this - one-argument pattern used in other :mod:`pyramid` tutorials and + one-argument pattern used in other :app:`Pyramid` tutorials and applications. Either calling convention will work in any - :mod:`pyramid` application; the calling conventions can be used + :app:`Pyramid` application; the calling conventions can be used interchangeably as necessary. In :term:`traversal` based applications, such as this tutorial, the context is used frequently within the body of a view method, so it makes sense to use the @@ -22,7 +22,7 @@ assumed to return a :term:`response` object. to avoid the visual "noise". We're going to define several :term:`view callable` functions then -wire them into :mod:`pyramid` using some :term:`view +wire them into :app:`Pyramid` using some :term:`view configuration` via :term:`ZCML`. The source code for this tutorial stage can be browsed via @@ -102,7 +102,7 @@ Note the contrast between this view callable and the ``view_wiki`` view callable. In the ``view_wiki`` view callable, we return a :term:`response` object. In the ``view_page`` view callable, we return a *dictionary*. It is *always* fine to return a -:term:`response` object from a :mod:`pyramid` view. Returning a +:term:`response` object from a :app:`Pyramid` view. Returning a dictionary is allowed only when there is a :term:`renderer` associated with the view callable in the view configuration. @@ -116,7 +116,7 @@ this view. It also acts as a handler for the form that is generated when we want to add a page object. The ``context`` of the ``add_page`` view is always a Wiki object (*not* a Page object). -The request :term:`subpath` in :mod:`pyramid` is the sequence of +The request :term:`subpath` in :app:`Pyramid` is the sequence of names that are found *after* the view name in the URL segments given in the ``PATH_INFO`` of the WSGI request as the result of :term:`traversal`. If our add view is invoked via, @@ -182,7 +182,7 @@ Adding Templates Most view callables we've added expected to be rendered via a :term:`template`. Each template is a :term:`Chameleon` template. The -default templating system in :mod:`pyramid` is a variant of +default templating system in :app:`Pyramid` is a variant of :term:`ZPT` provided by Chameleon. These templates will live in the ``templates`` directory of our tutorial package. diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst index 81ec61a63..ad717e72a 100644 --- a/docs/tutorials/wiki/distributing.rst +++ b/docs/tutorials/wiki/distributing.rst @@ -6,7 +6,7 @@ Once your application works properly, you can create a "tarball" from it by using the ``setup.py sdist`` command. The following commands assume your current working directory is the ``tutorial`` package we've created and that the parent directory of the ``tutorial`` -package is a virtualenv representing a :mod:`pyramid` environment. +package is a virtualenv representing a :app:`Pyramid` environment. On UNIX: diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst index 1fdc4be95..68f724902 100644 --- a/docs/tutorials/wiki/index.rst +++ b/docs/tutorials/wiki/index.rst @@ -3,7 +3,7 @@ ZODB + Traversal Wiki Tutorial (For Developers Familiar with Zope) ================================================================== -This tutorial introduces a :term:`traversal` -based :mod:`pyramid` +This tutorial introduces a :term:`traversal` -based :app:`Pyramid` application to a developer familiar with Python. It will be most familiar to developers with previous :term:`Zope` experience. When we're done with the tutorial, the developer will have created a basic Wiki application with diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 3e1b7552c..cb05611b7 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -52,7 +52,7 @@ Preparation, UNIX #. (Optional) Consider using ``source bin/activate`` to make your shell environment wired to use the virtualenv. -#. Use ``easy_install`` to get :mod:`pyramid` and its direct +#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies installed: .. code-block:: bash @@ -104,7 +104,7 @@ Preparation, Windows #. (Optional) Consider using ``bin\activate.bat`` to make your shell environment wired to use the virtualenv. -#. Use ``easy_install`` to get :mod:`pyramid` and its direct +#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies installed: .. code-block:: bat @@ -124,7 +124,7 @@ Preparation, Windows Making a Project ================ -Your next step is to create a project. :mod:`pyramid` supplies a +Your next step is to create a project. :app:`Pyramid` supplies a variety of templates to generate sample projects. For this tutorial, we will use the :term:`ZODB` -oriented template named ``pyramid_zodb``. @@ -255,8 +255,8 @@ assumptions: .. note:: - :mod:`pyramid` supports any persistent storage mechanism (e.g. a SQL - database or filesystem files, etc). :mod:`pyramid` also supports an + :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. diff --git a/docs/tutorials/wiki/viewdecorators.rst b/docs/tutorials/wiki/viewdecorators.rst index 2d58890e4..c2f068d86 100644 --- a/docs/tutorials/wiki/viewdecorators.rst +++ b/docs/tutorials/wiki/viewdecorators.rst @@ -154,7 +154,7 @@ Adding a Scan Directive In order for our decorators to be recognized, we must add a bit of boilerplate to our ``configure.zcml`` file which tells -:mod:`pyramid` to kick off a :term:`scan` at startup time. Add the +:app:`Pyramid` to kick off a :term:`scan` at startup time. Add the following tag anywhere beneath the ``<include package="pyramid.includes">`` tag but before the ending ``</configure>`` tag within ``configure.zcml``: diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 1691337e9..aaf0f0184 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -9,7 +9,7 @@ view, edit, and add pages to our wiki. For purposes of demonstration we'll change our application to allow only people whom possess a specific username (`editor`) to add and edit wiki pages but we'll continue allowing anyone with access to the server to view pages. -:mod:`pyramid` provides facilities for *authorization* and +:app:`Pyramid` provides facilities for *authorization* and *authentication*. We'll make use of both features to provide security to our application. @@ -29,11 +29,11 @@ Adding A Root Factory We're going to start to use a custom :term:`root factory` within our ``__init__.py`` file. The objects generated by the root factory will be used as the :term:`context` of each request to our application. In -order for :mod:`pyramid` declarative security to work properly, the +order for :app:`Pyramid` declarative security to work properly, the context object generated during a request must be decorated with security declarations; when we begin to use a custom root factory to generate our contexts, we can begin to make use of the declarative -security features of :mod:`pyramid`. +security features of :app:`Pyramid`. We'll modify our ``__init__.py``, passing in a :term:`root factory` to our :term:`Configurator` constructor. We'll point it at a new class we create @@ -52,7 +52,7 @@ inside our ``models.py`` file. Add the following statements to your self.__dict__.update(request.matchdict) The ``RootFactory`` class we've just added will be used by -:mod:`pyramid` to construct a ``context`` object. The context is +:app:`Pyramid` to construct a ``context`` object. The context is attached to the request object passed to our view callables as the ``context`` attribute. @@ -60,7 +60,7 @@ All of our context objects will possess an ``__acl__`` attribute that allows :data:`pyramid.security.Everyone` (a special principal) to view all pages, while allowing only a :term:`principal` named ``group:editors`` to edit and add pages. The ``__acl__`` attribute -attached to a context is interpreted specially by :mod:`pyramid` as +attached to a context is interpreted specially by :app:`Pyramid` as an access control list during view callable execution. See :ref:`assigning_acls` for more information about what an :term:`ACL` represents. @@ -76,7 +76,7 @@ We'll pass the ``RootFactory`` we created in the step above in as the Configuring an Authorization Policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For any :mod:`pyramid` application to perform authorization, we need to add a +For any :app:`Pyramid` application to perform authorization, we need to add a ``security.py`` module (we'll do that shortly) and we'll need to change our ``__init__.py`` file to add an :term:`authentication policy` and an :term:`authorization policy` which uses the ``security.py`` file for a @@ -87,7 +87,7 @@ We'll change our ``__init__.py`` file to enable an declarative security checking. We'll also change ``__init__.py`` to add a :meth:`pyramid.configuration.Configurator.add_view` call to points at our ``login`` :term:`view callable`, also known as a :term:`forbidden view`. -This configures our newly created login view to show up when :mod:`pyramid` +This configures our newly created login view to show up when :app:`Pyramid` detects that a view invocation can not be authorized. Also, we'll add ``view_permission`` arguments with the value ``edit`` to the ``edit_page`` and ``add_page`` routes. This indicates that the view callables which these diff --git a/docs/tutorials/wiki2/background.rst b/docs/tutorials/wiki2/background.rst index de35472bc..880b5b219 100644 --- a/docs/tutorials/wiki2/background.rst +++ b/docs/tutorials/wiki2/background.rst @@ -2,7 +2,7 @@ Background ========== -This tutorial presents a :mod:`pyramid` application that uses +This tutorial presents a :app:`Pyramid` application that uses technologies which will be familiar to someone with :term:`Pylons` experience. It uses :term:`SQLAlchemy` as a persistence mechanism and :term:`url dispatch` to map URLs to code. It can also be followed by @@ -12,6 +12,6 @@ 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* he will need a Windows system of any kind. -This tutorial is targeted at :mod:`pyramid` version 1.0. +This tutorial is targeted at :app:`Pyramid` version 1.0. Have fun! diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 7448563c7..30e9b5b3c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -4,7 +4,7 @@ Basic Layout The starter files generated by the ``pyramid_routesalchemy`` template are basic, but they provide a good orientation for the high-level -patterns common to most :term:`url dispatch` -based :mod:`pyramid` +patterns common to most :term:`url dispatch` -based :app:`Pyramid` projects. The source code for this tutorial stage can be browsed at diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 0826de660..83a8cf3f0 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -3,15 +3,15 @@ Defining Views ============== A :term:`view callable` in a :term:`url dispatch` -based -:mod:`pyramid` application is typically a simple Python function that +: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. -.. note:: A :mod:`pyramid` view can also be defined as callable +.. note:: A :app:`Pyramid` view can also be defined as callable which accepts *two* arguments: a :term:`context` and a :term:`request`. You'll see this two-argument pattern used in - other :mod:`pyramid` tutorials and applications. Either calling - convention will work in any :mod:`pyramid` application; the + other :app:`Pyramid` tutorials and applications. Either calling + convention will work in any :app:`Pyramid` application; the calling conventions can be used interchangeably as necessary. In :term:`url dispatch` based applications, however, the context object is rarely used in the view body itself, so within this @@ -117,7 +117,7 @@ content of our current page object. 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 this view returns a dictionary (as opposed to a -:term:`response` object) is a cue to :mod:`pyramid` that it should +: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 per the @@ -147,7 +147,7 @@ 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, so we create a dummy Page object in order to satisfy the edit form's desire to have *some* page object exposed as ``page``, and -:mod:`pyramid` will render the template associated with this view +:app:`Pyramid` will render the template associated with this view to a response. If the view execution *is* a result of a form submission (if the @@ -196,7 +196,7 @@ Adding Templates The views we've added all reference a :term:`template`. Each template is a :term:`Chameleon` template. The default templating system in -:mod:`pyramid` is a variant of :term:`ZPT` provided by +:app:`Pyramid` is a variant of :term:`ZPT` provided by :term:`Chameleon`. These templates will live in the ``templates`` directory of our tutorial package. diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst index 44e0291d1..f4421e145 100644 --- a/docs/tutorials/wiki2/distributing.rst +++ b/docs/tutorials/wiki2/distributing.rst @@ -6,7 +6,7 @@ Once your application works properly, you can create a "tarball" from it by using the ``setup.py sdist`` command. The following commands assume your current working directory is the ``tutorial`` package we've created and that the parent directory of the ``tutorial`` -package is a virtualenv representing a :mod:`pyramid` environment. +package is a virtualenv representing a :app:`Pyramid` environment. On UNIX: diff --git a/docs/tutorials/wiki2/index.rst b/docs/tutorials/wiki2/index.rst index fd1b6e2a1..03b405048 100644 --- a/docs/tutorials/wiki2/index.rst +++ b/docs/tutorials/wiki2/index.rst @@ -4,7 +4,7 @@ SQLAlchemy + URL Dispatch Wiki Tutorial (For Developers Familiar with Pylons 1) =============================================================================== This tutorial introduces a :term:`SQLAlchemy` and :term:`url dispatch` -based -:mod:`pyramid` application to a developer familiar with Python, and will be +:app:`Pyramid` application to a developer familiar with Python, and will be most familiar to developers who have used the :term:`Pylons` 1.X web framework. When the tutorial is finished, the developer will have created a basic Wiki application with authentication. diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 37a99171f..e6fd5e6b9 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -56,7 +56,7 @@ Preparation, UNIX #. (Optional) Consider using ``source bin/activate`` to make your shell environment wired to use the virtualenv. -#. Use ``easy_install`` to get :mod:`pyramid` and its direct +#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies installed: .. code-block:: text @@ -107,7 +107,7 @@ Preparation, Windows #. (Optional) Consider using ``bin\activate.bat`` to make your shell environment wired to use the virtualenv. -#. Use ``easy_install`` to get :mod:`pyramid` and its direct +#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies installed: .. code-block:: text @@ -127,7 +127,7 @@ Preparation, Windows Making a Project ================ -Your next step is to create a project. :mod:`pyramid` supplies a +Your next step is to create a project. :app:`Pyramid` supplies a variety of templates to generate sample projects. We will use the ``pyramid_routesalchemy`` template, which generates an application that uses :term:`SQLAlchemy` and :term:`URL dispatch`. @@ -277,7 +277,7 @@ the following assumptions: .. note:: - :mod:`pyramid` supports any persistent storage mechanism (e.g. object + :app:`Pyramid` supports any persistent storage mechanism (e.g. object database or filesystem files, etc). It also supports an additional mechanism to map URLs to code (:term:`traversal`). However, for the purposes of this tutorial, we'll only be using url dispatch and diff --git a/docs/tutorials/zeo/index.rst b/docs/tutorials/zeo/index.rst index a63afcf90..229ec2ffc 100644 --- a/docs/tutorials/zeo/index.rst +++ b/docs/tutorials/zeo/index.rst @@ -4,18 +4,18 @@ Using ZODB with ZEO =================== :term:`ZODB` is a Python object persistence mechanism. :term:`ZODB` -works well as a storage mechanism for :mod:`pyramid` applications, +works well as a storage mechanism for :app:`Pyramid` applications, especially in applications that use :term:`traversal`. :term:`ZEO` is an extension to ZODB which allows more than one process to simultaneously communicate with a ZODB storage. Making a ZODB database accessible to more than one process means that you can debug -your application objects at the same time that a :mod:`pyramid` +your application objects at the same time that a :app:`Pyramid` server that accesses the database is running, and will also allow your application to run under multiprocess configurations, such as those exposed by :term:`mod_wsgi`. -The easiest way to get started with ZODB in a :mod:`pyramid` application is +The easiest way to get started with ZODB in a :app:`Pyramid` application is to use the ZODB ``pyramid_zodb`` paster template. See :ref:`additional_paster_templates` for more information about using this template. However, the Paster template does not set up a ZEO-capable @@ -24,7 +24,7 @@ application. This chapter shows you how to do that "from scratch". Installing Dependencies ----------------------- -#. Edit your :mod:`pyramid` application's ``setup.py`` file, adding +#. Edit your :app:`Pyramid` application's ``setup.py`` file, adding the following packages to the ``install_requires`` of the application: @@ -142,7 +142,7 @@ Configuration </blobstorage> #. For the purposes of this tutorial we'll assume that you want your - :mod:`pyramid` application's :term:`root` object to be a + :app:`Pyramid` application's :term:`root` object to be a "folderish" object. To achieve this, change your application's ``models.py`` file to look like the below: diff --git a/docs/tutorials/zodbsessions/index.rst b/docs/tutorials/zodbsessions/index.rst index c32b457d5..9582e5de4 100644 --- a/docs/tutorials/zodbsessions/index.rst +++ b/docs/tutorials/zodbsessions/index.rst @@ -21,13 +21,13 @@ sessioning to your application. usage documentation <http://docs.repoze.org/session/usage.html>`_. If you don't want to use ZODB to do sessioning, you might choose to use a relational/filestorage sessioning system such as `Beaker - <http://pypi.python.org/pypi/Beaker>`_. :mod:`pyramid` is fully + <http://pypi.python.org/pypi/Beaker>`_. :app:`Pyramid` is fully compatible with this system too. Installing Dependencies ----------------------- -#. Edit your :mod:`pyramid` application's ``setup.py`` file, adding +#. Edit your :app:`Pyramid` application's ``setup.py`` file, adding the following packages to the ``install_requires`` of the application: |