diff options
| -rw-r--r-- | docs/tutorials/wiki/definingmodels.rst | 16 | ||||
| -rw-r--r-- | docs/tutorials/wiki/definingviews.rst | 142 | ||||
| -rw-r--r-- | docs/tutorials/wiki/src/models/setup.py | 9 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/definingviews.rst | 2 |
4 files changed, 85 insertions, 84 deletions
diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst index 8352c5344..3d2d01061 100644 --- a/docs/tutorials/wiki/definingmodels.rst +++ b/docs/tutorials/wiki/definingmodels.rst @@ -127,22 +127,6 @@ When we're done changing ``tests.py``, it will look something like so: :linenos: :language: python -Declaring Dependencies in Our ``setup.py`` File ------------------------------------------------ - -Our application now depends on packages which are not dependencies of the -original "tutorial" application as it was generated by the ``paster create`` -command. We'll add these dependencies to our ``tutorial`` package's -``setup.py`` file by assigning these dependencies to both the -``install_requires`` and the ``tests_require`` parameters to the ``setup`` -function. In particular, we require the ``docutils`` package. - -Our resulting ``setup.py`` should look like so: - -.. literalinclude:: src/models/setup.py - :linenos: - :language: python - Running the Tests ----------------- diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 31900233c..233e571f1 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -2,38 +2,26 @@ Defining Views ============== -Conventionally, :term:`view callable` objects are defined within a -``views.py`` module in an :app:`Pyramid` application. There is nothing -automagically special about the filename ``views.py``. Files implementing -views often have ``view`` in their filenames (or may live in a Python -subpackage of your application package named ``views``), but this is only by -convention. A project may have many views throughout its codebase in -arbitrarily-named files. In this application, however, we'll be continuing -to use the ``views.py`` module, because there's no reason to break -convention. - -A :term:`view callable` in a :app:`Pyramid` application is typically a simple -Python function that accepts a single parameter: :term:`request`. A view -callable is assumed to return a :term:`response` object. - -However, a :app:`Pyramid` view can also be defined as callable which accepts -*two* arguments: a :term:`context` and a :term:`request`. In :term:`url -dispatch` based applications, the context resource is rarely used in the view -body itself, so within code that uses URL-dispatch-only, it's common to -define views as callables that accept only a ``request`` to avoid the visual -"noise" of a ``context`` argument. This application, however, uses -:term:`traversal` to map URLs to a context :term:`resource`, and since our -:term:`resource tree` also represents our application's "domain model", we're -often interested in the context, because it represents the persistent storage -of our application. For this reason, having ``context`` in the callable -argument list is not "noise" to us; instead it's actually rather important -within the view code we'll define in this application. - -The single-arg (``request`` -only) or two-arg (``context`` and ``request``) -calling conventions will work in any :app:`Pyramid` application for any view; -they can be used interchangeably as necessary. We'll be using the -two-argument ``(context, request)`` view callable argument list syntax in -this application. +A :term:`view callable` in a :term:`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 :app:`Pyramid` view can also be defined as callable + which accepts *only* a :term:`request` argument. You'll see + this one-argument pattern used in 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:`traversal` based applications, + URLs are mapped to a context :term:`resource`, and since our + :term:`resource tree` also represents our application's + "domain model", we're often interested in the context, because + it represents the persistent storage of our application. For + this reason, in this tutorial we define views as callables that + accept ``context`` in the callable argument list. If you do + need the ``context`` within a view function that only takes + the request as a single argument, you can obtain it via + ``request.context``. We're going to define several :term:`view callable` functions then wire them into :app:`Pyramid` using some :term:`view configuration`. @@ -42,6 +30,28 @@ The source code for this tutorial stage can be browsed via `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/views/ <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/views/>`_. +Declaring Dependencies in Our ``setup.py`` File +=============================================== + +The view code in our application will depend on a package which is not a +dependency of the original "tutorial" application. The original "tutorial" +application was generated by the ``paster create`` command; it doesn't know +about our custom application requirements. We need to add a dependency on +the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by +assigning this dependency to the ``install_requires`` parameter in the +``setup`` function. + +Our resulting ``setup.py`` should look like so: + +.. literalinclude:: src/views/setup.py + :linenos: + :language: python + +.. note:: After these new dependencies are added, you will need to + rerun ``python setup.py develop`` inside the root of the + ``tutorial`` package to obtain and register the newly added + dependency package. + Adding View Functions ===================== @@ -51,6 +61,14 @@ answer on the root URL), another named ``view_page`` will display an individual page, another named ``add_page`` will allow a page to be added, and a final view named ``edit_page`` will allow a page to be edited. +.. note:: + + There is nothing special about the filename ``views.py``. A project may + have many view callables throughout its codebase in arbitrarily-named + files. Files implementing view callables often have ``view`` in their + filenames (or may live in a Python subpackage of your application package + named ``views``), but this is only by convention. + The ``view_wiki`` view function ------------------------------- @@ -173,7 +191,7 @@ with a ``@view_config`` decorator which names the string ``edit_page`` as its :term:`view name` (via ``name=``), the class ``tutorial.models.Page`` as its context, and the renderer named ``templates/edit.pt``. This means that when a Page resource is the context, and a :term:`view name` exists as the result -of traverasal named ``edit_page``, this view will be used. We inform +of traversal named ``edit_page``, this view will be used. We inform :app:`Pyramid` this view will use the ``templates/edit.pt`` template file as a ``renderer``. @@ -193,8 +211,8 @@ If the view execution *is* a result of a form submission (if the expression attribute of the page context. It then redirects to the default view of the context (the page), which will always be the ``view_page`` view. -Viewing the Result of Our Edits to ``views.py`` -=============================================== +Viewing the Result of all Our Edits to ``views.py`` +=================================================== The result of all of our edits to ``views.py`` will leave it looking like this: @@ -269,12 +287,38 @@ replicate within the body of this guide, however it is available `online This CSS file will be accessed via e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to -``add_static_view`` directive we've made in the ``__init__`` file. Any +``add_static_view`` directive we've made in the ``__init__.py`` file. Any number and type of static assets can be placed in this directory (or subdirectories) and are just referred to by URL or by using the convenience method ``static_url`` e.g. ``request.static_url('{{package}}:static/foo.css')`` within templates. +Viewing the Application in a Browser +==================================== + +We can finally examine our application in a +browser. The views we'll try are as follows: + +- Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki`` + view. This always redirects to the ``view_page`` view of the ``FrontPage`` + Page resource. + +- Visiting ``http://localhost:6543/FrontPage/`` in a browser invokes + the ``view_page`` view of the front page resource. This is + because it's the *default view* (a view without a ``name``) for Page + resources. + +- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser + invokes the edit view for the ``FrontPage`` Page resource. + +- Visiting ``http://localhost:6543/add_page/SomePageName`` in a + browser invokes the add view for a Page. + +- To generate an error, visit ``http://localhost:6543/add_page`` which + will generate an ``IndexError`` for the expression + ``request.subpath[0]``. You'll see an interactive traceback + facility provided by :term:`WebError`. + Testing the Views ================= @@ -319,29 +363,3 @@ The expected result looks something like: Ran 9 tests in 0.203s OK - -Viewing the Application in a Browser -==================================== - -Once we've completed our edits, we can finally examine our application in a -browser. The views we'll try are as follows: - -- Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki`` - view. This always redirects to the ``view_page`` view of the ``FrontPage`` - Page resource. - -- Visiting ``http://localhost:6543/FrontPage/`` in a browser invokes - the ``view_page`` view of the front page resource. This is - because it's the *default view* (a view without a ``name``) for Page - resources. - -- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser - invokes the edit view for the ``FrontPage`` Page resource. - -- Visiting ``http://localhost:6543/add_page/SomePageName`` in a - browser invokes the add view for a Page. - -- To generate an error, visit ``http://localhost:6543/add_page`` which - will generate an ``IndexError`` for the expression - ``request.subpath[0]``. You'll see an interactive traceback - facility provided by :term:`WebError`. diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py index daa5e5eb1..2d540d65b 100644 --- a/docs/tutorials/wiki/src/models/setup.py +++ b/docs/tutorials/wiki/src/models/setup.py @@ -13,7 +13,6 @@ requires = [ 'repoze.retry', 'ZODB3', 'WebError', - 'docutils', ] setup(name='tutorial', @@ -21,9 +20,8 @@ setup(name='tutorial', description='tutorial', long_description=README + '\n\n' + CHANGES, classifiers=[ - "Intended Audience :: Developers", - "Framework :: Pylons", "Programming Language :: Python", + "Framework :: Pylons", "Topic :: Internet :: WWW/HTTP", "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", ], @@ -34,8 +32,8 @@ setup(name='tutorial', packages=find_packages(), include_package_data=True, zip_safe=False, - install_requires=requires, - tests_require=requires, + install_requires = requires, + tests_require= requires, test_suite="tutorial", entry_points = """\ [paste.app_factory] @@ -43,3 +41,4 @@ setup(name='tutorial', """, paster_plugins=['pyramid'], ) + diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 874c49d4c..c5a452d11 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -262,7 +262,7 @@ to replicate within the body of this guide, however it is available `online This CSS file will be accessed via e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to -``add_static_view`` directive we've made in the ``__init__`` file. Any +``add_static_view`` directive we've made in the ``__init__.py`` file. Any number and type of static assets can be placed in this directory (or subdirectories) and are just referred to by URL or by using the convenience method ``static_url`` |